# 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)