973502f26e
Schema additions for issues #37-41: New models: - Domain (#37): Life domains (work, marriage, homelab, etc.) - Idea (#38): Brain dumps with pgvector embeddings - Relationship (#39): Generic entity linking (blocks, depends_on) - Agent (#40): ClawdBot agent tracking with metrics - AgentSession (#40): Conversation session tracking - WidgetDefinition (#41): HUD widget registry - UserLayout (#41): Per-user dashboard configuration Updated models: - Task, Event, Project: Added domainId foreign key - User, Workspace: Added new relations New enums: - IdeaStatus: CAPTURED, PROCESSING, ACTIONABLE, ARCHIVED, DISCARDED - RelationshipType: BLOCKS, BLOCKED_BY, DEPENDS_ON, etc. - AgentStatus: IDLE, WORKING, WAITING, ERROR, TERMINATED - EntityType: Added IDEA, DOMAIN Migration: 20260129182803_add_domains_ideas_agents_widgets
350 lines
6.9 KiB
Markdown
350 lines
6.9 KiB
Markdown
# Docker Quick Reference
|
|
|
|
Quick command reference for Mosaic Stack Docker operations.
|
|
|
|
## Starting Services
|
|
|
|
```bash
|
|
# Core services only (PostgreSQL, Valkey, API, Web)
|
|
docker compose up -d
|
|
|
|
# With Authentik OIDC
|
|
docker compose --profile authentik up -d
|
|
|
|
# With Ollama AI
|
|
docker compose --profile ollama up -d
|
|
|
|
# All services
|
|
docker compose --profile full up -d
|
|
|
|
# Or use Makefile
|
|
make docker-up # Core services
|
|
make docker-up-full # All services
|
|
```
|
|
|
|
## Stopping Services
|
|
|
|
```bash
|
|
# Stop (keeps data)
|
|
docker compose down
|
|
|
|
# Stop and remove volumes (deletes data!)
|
|
docker compose down -v
|
|
```
|
|
|
|
## Viewing Status
|
|
|
|
```bash
|
|
# List running services
|
|
docker compose ps
|
|
|
|
# View logs (all services)
|
|
docker compose logs -f
|
|
|
|
# View logs (specific service)
|
|
docker compose logs -f api
|
|
|
|
# Last 100 lines
|
|
docker compose logs --tail=100 api
|
|
|
|
# Resource usage
|
|
docker stats
|
|
```
|
|
|
|
## Service Management
|
|
|
|
```bash
|
|
# Restart all services
|
|
docker compose restart
|
|
|
|
# Restart specific service
|
|
docker compose restart api
|
|
|
|
# Rebuild and restart
|
|
docker compose up -d --build
|
|
|
|
# Pull latest images
|
|
docker compose pull
|
|
```
|
|
|
|
## Database Operations
|
|
|
|
```bash
|
|
# PostgreSQL shell
|
|
docker compose exec postgres psql -U mosaic -d mosaic
|
|
|
|
# Run migrations
|
|
docker compose exec api pnpm prisma:migrate:prod
|
|
|
|
# Seed data
|
|
docker compose exec api pnpm prisma:seed
|
|
|
|
# Backup database
|
|
docker compose exec postgres pg_dump -U mosaic mosaic > backup.sql
|
|
|
|
# Restore database
|
|
cat backup.sql | docker compose exec -T postgres psql -U mosaic -d mosaic
|
|
```
|
|
|
|
## Cache Operations
|
|
|
|
```bash
|
|
# Valkey CLI
|
|
docker compose exec valkey valkey-cli
|
|
|
|
# Check cache health
|
|
docker compose exec valkey valkey-cli ping
|
|
|
|
# Flush cache
|
|
docker compose exec valkey valkey-cli FLUSHALL
|
|
```
|
|
|
|
## Container Access
|
|
|
|
```bash
|
|
# API container shell
|
|
docker compose exec api sh
|
|
|
|
# Web container shell
|
|
docker compose exec web sh
|
|
|
|
# Run command in container
|
|
docker compose exec api node -v
|
|
```
|
|
|
|
## Debugging
|
|
|
|
```bash
|
|
# Check service health
|
|
docker compose ps
|
|
|
|
# View container details
|
|
docker inspect mosaic-api
|
|
|
|
# Check networks
|
|
docker network ls
|
|
docker network inspect mosaic-internal
|
|
|
|
# Check volumes
|
|
docker volume ls
|
|
docker volume inspect mosaic-postgres-data
|
|
|
|
# Test connectivity
|
|
docker compose exec api nc -zv postgres 5432
|
|
docker compose exec api nc -zv valkey 6379
|
|
```
|
|
|
|
## Health Endpoints
|
|
|
|
```bash
|
|
# API health
|
|
curl http://localhost:3001/health
|
|
|
|
# Web (returns HTML)
|
|
curl http://localhost:3000
|
|
|
|
# Authentik health (if enabled)
|
|
curl http://localhost:9000/-/health/live/
|
|
|
|
# Ollama health (if enabled)
|
|
curl http://localhost:11434/api/tags
|
|
```
|
|
|
|
## Cleanup
|
|
|
|
```bash
|
|
# Remove stopped containers
|
|
docker compose down
|
|
|
|
# Remove containers and volumes
|
|
docker compose down -v
|
|
|
|
# Remove all unused Docker resources
|
|
docker system prune -a
|
|
|
|
# Remove unused volumes only
|
|
docker volume prune
|
|
```
|
|
|
|
## Environment Management
|
|
|
|
```bash
|
|
# Check current environment
|
|
docker compose config
|
|
|
|
# Validate compose file
|
|
docker compose config --quiet
|
|
|
|
# Use specific env file
|
|
docker compose --env-file .env.production up -d
|
|
```
|
|
|
|
## Profiles
|
|
|
|
```bash
|
|
# Available profiles
|
|
# - authentik: Authentik OIDC stack
|
|
# - ollama: Ollama AI service
|
|
# - full: All optional services
|
|
|
|
# Set profile via environment
|
|
export COMPOSE_PROFILES=authentik,ollama
|
|
docker compose up -d
|
|
|
|
# Or in .env file
|
|
echo "COMPOSE_PROFILES=full" >> .env
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
```bash
|
|
# Container won't start - check logs
|
|
docker compose logs <service>
|
|
|
|
# Port conflict - check what's using the port
|
|
lsof -i :3001
|
|
|
|
# Permission errors - check permissions
|
|
docker compose exec postgres ls -la /var/lib/postgresql/data
|
|
|
|
# Network issues - recreate networks
|
|
docker compose down
|
|
docker network prune
|
|
docker compose up -d
|
|
|
|
# Volume issues - check volume
|
|
docker volume inspect mosaic-postgres-data
|
|
|
|
# Reset everything (DANGER: deletes all data)
|
|
docker compose down -v
|
|
docker system prune -af
|
|
docker volume prune -f
|
|
```
|
|
|
|
## Performance Tuning
|
|
|
|
```bash
|
|
# View resource usage
|
|
docker stats
|
|
|
|
# Limit container resources (in docker-compose.override.yml)
|
|
services:
|
|
api:
|
|
deploy:
|
|
resources:
|
|
limits:
|
|
cpus: '1.0'
|
|
memory: 1G
|
|
|
|
# Adjust PostgreSQL settings in .env
|
|
POSTGRES_SHARED_BUFFERS=512MB
|
|
POSTGRES_EFFECTIVE_CACHE_SIZE=2GB
|
|
|
|
# Adjust Valkey memory in .env
|
|
VALKEY_MAXMEMORY=512mb
|
|
```
|
|
|
|
## Backup & Restore
|
|
|
|
```bash
|
|
# Backup PostgreSQL database
|
|
docker compose exec postgres pg_dump -U mosaic mosaic > backup-$(date +%Y%m%d).sql
|
|
|
|
# Backup volume
|
|
docker run --rm \
|
|
-v mosaic-postgres-data:/data \
|
|
-v $(pwd):/backup \
|
|
alpine tar czf /backup/postgres-backup.tar.gz /data
|
|
|
|
# Restore database
|
|
cat backup-20260128.sql | docker compose exec -T postgres psql -U mosaic -d mosaic
|
|
|
|
# Restore volume
|
|
docker run --rm \
|
|
-v mosaic-postgres-data:/data \
|
|
-v $(pwd):/backup \
|
|
alpine tar xzf /backup/postgres-backup.tar.gz -C /
|
|
```
|
|
|
|
## Security
|
|
|
|
```bash
|
|
# Scan images for vulnerabilities
|
|
docker scout cves mosaic-api
|
|
|
|
# Check running processes in container
|
|
docker compose exec api ps aux
|
|
|
|
# View container security options
|
|
docker inspect mosaic-api --format='{{.HostConfig.SecurityOpt}}'
|
|
|
|
# Rotate secrets (update .env, then)
|
|
docker compose up -d --force-recreate
|
|
```
|
|
|
|
## Makefile Commands
|
|
|
|
```bash
|
|
make help # Show all commands
|
|
make docker-up # Start core services
|
|
make docker-up-full # Start all services
|
|
make docker-down # Stop services
|
|
make docker-logs # View logs
|
|
make docker-ps # Service status
|
|
make docker-build # Rebuild images
|
|
make docker-restart # Restart services
|
|
make docker-test # Run smoke test
|
|
make docker-clean # Remove containers and volumes
|
|
```
|
|
|
|
## npm Scripts
|
|
|
|
```bash
|
|
pnpm docker:up # Start services
|
|
pnpm docker:down # Stop services
|
|
pnpm docker:logs # View logs
|
|
pnpm docker:ps # Service status
|
|
pnpm docker:build # Rebuild images
|
|
pnpm docker:restart # Restart services
|
|
pnpm test:docker # Run integration tests
|
|
```
|
|
|
|
## One-Liners
|
|
|
|
```bash
|
|
# Quick health check all services
|
|
docker compose ps | grep -E 'Up|healthy'
|
|
|
|
# Follow logs for all services with timestamps
|
|
docker compose logs -f --timestamps
|
|
|
|
# Restart unhealthy services
|
|
docker compose ps --format json | jq -r 'select(.Health == "unhealthy") | .Service' | xargs docker compose restart
|
|
|
|
# Show disk usage by service
|
|
docker system df -v
|
|
|
|
# Export all logs to file
|
|
docker compose logs > logs-$(date +%Y%m%d-%H%M%S).txt
|
|
|
|
# Check which ports are exposed
|
|
docker compose ps --format json | jq -r '.[] | "\(.Service): \(.Publishers)"'
|
|
```
|
|
|
|
## Service URLs (Default Ports)
|
|
|
|
- **Web**: http://localhost:3000
|
|
- **API**: http://localhost:3001
|
|
- **API Health**: http://localhost:3001/health
|
|
- **PostgreSQL**: localhost:5432
|
|
- **Valkey**: localhost:6379
|
|
- **Authentik**: http://localhost:9000 (if enabled)
|
|
- **Ollama**: http://localhost:11434 (if enabled)
|
|
- **Prisma Studio**: http://localhost:5555 (when running)
|
|
|
|
## Next Steps
|
|
|
|
- [Full Deployment Guide](README.md)
|
|
- [Configuration Reference](../3-configuration/3-docker.md)
|
|
- [Troubleshooting Guide](README.md#troubleshooting)
|