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

Docker Deployment

Complete guide for deploying Mosaic Stack using Docker Compose.

Overview

Mosaic Stack provides a turnkey Docker Compose setup that includes:

• PostgreSQL 17 with pgvector extension
• Valkey (Redis-compatible cache)
• Traefik (optional reverse proxy)
• Authentik (optional OIDC provider)
• Ollama (optional AI service)
• Mosaic API (NestJS backend)
• Mosaic Web (Next.js frontend)

Quick Start

Start the entire stack with one command:

# Copy environment configuration
cp .env.example .env

# Edit .env with your settings
nano .env

# Start core services (PostgreSQL, Valkey, API, Web)
docker compose up -d

# Check service status
docker compose ps

# View logs
docker compose logs -f

That's it! Your Mosaic Stack is now running:

• Web: http://localhost:3000
• API: http://localhost:3001
• PostgreSQL: localhost:5432
• Valkey: localhost:6379

Service Profiles

Mosaic Stack uses Docker Compose profiles to enable optional services:

Core Services (Always Active)

• postgres - PostgreSQL database
• valkey - Valkey cache
• api - Mosaic API
• web - Mosaic Web

Optional Services (Profiles)

Traefik (Reverse Proxy)

# Start with bundled Traefik
docker compose --profile traefik-bundled up -d

# Or set in .env
COMPOSE_PROFILES=traefik-bundled

Services included:

• traefik - Traefik reverse proxy with dashboard (http://localhost:8080)

See Traefik Integration Guide for detailed configuration options including upstream mode.

Authentik (OIDC Provider)

# Start with Authentik
docker compose --profile authentik up -d

# Or set in .env
COMPOSE_PROFILES=authentik

Services included:

• authentik-postgres - Authentik database
• authentik-redis - Authentik cache
• authentik-server - Authentik OIDC server (http://localhost:9000)
• authentik-worker - Authentik background worker

Ollama (AI Service)

# Start with Ollama
docker compose --profile ollama up -d

# Or set in .env
COMPOSE_PROFILES=ollama

Services included:

• ollama - Ollama LLM service (http://localhost:11434)

All Services

# Start everything
docker compose --profile full up -d

# Or set in .env
COMPOSE_PROFILES=full

Deployment Modes

Turnkey Deployment (Recommended for Development)

Uses all bundled services:

# Start core services
docker compose up -d

# Or with optional services
docker compose --profile full up -d

Customized Deployment (Production)

Use external services for production:

1. Copy override template:

   cp docker-compose.override.yml.example docker-compose.override.yml
   

2. Edit docker-compose.override.yml to:

   • Disable bundled services
   • Point to external services
   • Add custom configuration

3. Start stack:

   docker compose up -d
   

Docker automatically merges docker-compose.yml and docker-compose.override.yml.

Architecture

Network Configuration

Mosaic Stack uses two Docker networks to organize service communication:

mosaic-internal (Backend Services)

• Purpose: Isolates database and cache services
• Services:
  • PostgreSQL (main database)
  • Valkey (main cache)
  • Authentik PostgreSQL
  • Authentik Redis
  • Ollama (when using bundled service)
• Connectivity:
  • Not marked as internal: true to allow API to reach external services
  • API can connect to external Authentik and Ollama instances
  • Database and cache services only accessible within Docker network
  • No direct external access to database/cache ports (unless explicitly exposed)

mosaic-public (Frontend Services)

• Purpose: Services that need external network access
• Services:
  • Mosaic API (needs to reach Authentik OIDC and external Ollama)
  • Mosaic Web
  • Authentik Server (receives OIDC callbacks)
• Connectivity: Full external network access for API integrations

Network Security Notes

1. Why mosaic-internal is not marked internal: The API service needs to:

   • Connect to external Authentik servers for OIDC authentication
   • Connect to external Ollama services when using remote AI
   • Make outbound HTTP requests for integrations

2. Database/Cache Protection: Even though the network allows external access:

   • PostgreSQL and Valkey are NOT exposed on host ports by default
   • Only accessible via internal Docker DNS (postgres:5432, valkey:6379)
   • To expose for development, explicitly set ports in .env

3. Production Recommendations:

   • Use firewall rules to restrict container egress traffic
   • Use reverse proxy (Traefik, nginx) for API/Web with TLS
   • Use external managed PostgreSQL and Valkey services
   • Implement network policies in orchestration platforms (Kubernetes)

Volume Management

Persistent data volumes:

• mosaic-postgres-data - PostgreSQL data
• mosaic-valkey-data - Valkey persistence
• mosaic-authentik-postgres-data - Authentik database
• mosaic-authentik-redis-data - Authentik cache
• mosaic-authentik-media - Authentik media files
• mosaic-authentik-certs - Authentik certificates
• mosaic-authentik-templates - Authentik templates
• mosaic-ollama-data - Ollama models

Health Checks

All services include health checks with automatic restart:

• PostgreSQL: pg_isready check every 10s
• Valkey: valkey-cli ping every 10s
• API: HTTP GET /health every 30s
• Web: HTTP GET / every 30s
• Authentik: HTTP GET /-/health/live/ every 30s

Common Operations

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart api

Stop Services

# Stop all (keeps data)
docker compose down

# Stop and remove volumes (WARNING: deletes all data)
docker compose down -v

Execute Commands in Containers

# PostgreSQL shell
docker compose exec postgres psql -U mosaic -d mosaic

# API shell
docker compose exec api sh

# Run Prisma migrations
docker compose exec api pnpm prisma:migrate:prod

Update Services

# Pull latest images
docker compose pull

# Rebuild and restart
docker compose up -d --build

Configuration

See Configuration Guide for detailed environment variable documentation.

Key Environment Variables

# Application Ports
API_PORT=3001
WEB_PORT=3000

# Database
DATABASE_URL=postgresql://mosaic:password@postgres:5432/mosaic
POSTGRES_USER=mosaic
POSTGRES_PASSWORD=change-me

# Cache
VALKEY_URL=redis://valkey:6379

# Authentication (if using Authentik)
OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

# JWT
JWT_SECRET=change-this-to-a-random-secret

Troubleshooting

Service Won't Start

Check logs:

docker compose logs <service-name>

Common issues:

• Port already in use: Change port in .env
• Health check failing: Wait longer or check service logs
• Missing environment variables: Check .env file

Database Connection Issues

1. Verify PostgreSQL is healthy:

   docker compose ps postgres
   

2. Check database logs:

   docker compose logs postgres
   

3. Test connection:

   docker compose exec postgres psql -U mosaic -d mosaic -c "SELECT 1;"
   

Performance Issues

1. Adjust PostgreSQL settings in .env:

   POSTGRES_SHARED_BUFFERS=512MB
   POSTGRES_EFFECTIVE_CACHE_SIZE=2GB
   POSTGRES_MAX_CONNECTIONS=200
   

2. Adjust Valkey memory:

   VALKEY_MAXMEMORY=512mb
   

3. Check resource usage:

   docker stats
   

Reset Everything

# Stop and remove all containers, networks, and volumes
docker compose down -v

# Remove all Mosaic images
docker images | grep mosaic | awk '{print $3}' | xargs docker rmi

# Start fresh
docker compose up -d --build

Production Considerations

Security

1. Change default passwords in .env:

   • POSTGRES_PASSWORD
   • AUTHENTIK_POSTGRES_PASSWORD
   • AUTHENTIK_SECRET_KEY
   • JWT_SECRET

2. Use secrets management:

   • Docker secrets
   • External secret manager (Vault, AWS Secrets Manager)

3. Network security:

   • Use reverse proxy (see Traefik Integration)
   • Enable HTTPS/TLS
   • Restrict port exposure

4. Regular updates:

   • Keep images updated
   • Monitor security advisories

Backup

Backup volumes regularly:

# Backup PostgreSQL
docker compose exec postgres pg_dump -U mosaic mosaic > backup.sql

# Backup volumes
docker run --rm -v mosaic-postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data.tar.gz /data

Monitoring

Consider adding:

• Prometheus for metrics
• Grafana for dashboards
• Loki for log aggregation
• Alertmanager for alerts

Scaling

For production scaling:

• Use external PostgreSQL (managed service)
• Use external Redis/Valkey cluster
• Load balance multiple API instances
• Use CDN for static assets

Next Steps

• Traefik Integration - Reverse proxy setup and configuration
• Installation Guide - Detailed setup instructions
• Configuration Guide - Environment variables
• Development Guide - Development workflow
• API Documentation - API reference