stack/docs/1-getting-started/4-docker-deployment/QUICK-REFERENCE.md

Docker Quick Reference

Quick command reference for Mosaic Stack Docker operations.

Starting Services

# 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

# Stop (keeps data)
docker compose down

# Stop and remove volumes (deletes data!)
docker compose down -v

Viewing Status

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

# 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
• Configuration Reference
• Troubleshooting Guide