stack/docs/1-getting-started/2-installation/3-docker-setup.md

Docker Setup

Containerized deployment for production or quick testing.

Prerequisites

• Docker 24+ and Docker Compose 2.20+
• Git 2.x

See Prerequisites for installation instructions.

Step 1: Clone Repository

git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack
cd mosaic-stack

Step 2: Configure Environment

cp .env.example .env
nano .env  # Configure as needed

Key variables for Docker deployment:

# Database (Docker internal networking)
DATABASE_URL=postgresql://mosaic:mosaic_dev_password@postgres:5432/mosaic
POSTGRES_USER=mosaic
POSTGRES_PASSWORD=mosaic_dev_password
POSTGRES_DB=mosaic

# Valkey (Docker internal networking)
VALKEY_URL=redis://valkey:6379

# Application URLs
NEXT_PUBLIC_API_URL=http://localhost:3001

# JWT
JWT_SECRET=$(openssl rand -base64 32)
JWT_EXPIRATION=24h

Step 3: Start Services

Option A: Core Services Only (Recommended for Development)

Start PostgreSQL, Valkey, API, and Web:

# Start core stack
docker compose up -d

# View startup logs
docker compose logs -f

# Check service status
docker compose ps

Option B: With Optional Services

Enable Authentik OIDC and/or Ollama AI:

# With Authentik only
docker compose --profile authentik up -d

# With Ollama only
docker compose --profile ollama up -d

# With all optional services
docker compose --profile full up -d

# Or set in .env file
echo "COMPOSE_PROFILES=full" >> .env
docker compose up -d

Services available:

Service	Container	Port	Profile	Purpose
PostgreSQL	mosaic-postgres	5432	core	Database with pgvector
Valkey	mosaic-valkey	6379	core	Redis-compatible cache
API	mosaic-api	3001	core	NestJS backend
Web	mosaic-web	3000	core	Next.js frontend
Authentik Server	mosaic-authentik-server	9000, 9443	authentik	OIDC provider
Authentik Worker	mosaic-authentik-worker	-	authentik	Background jobs
Authentik PostgreSQL	mosaic-authentik-postgres	-	authentik	Auth database
Authentik Redis	mosaic-authentik-redis	-	authentik	Auth cache
Ollama	mosaic-ollama	11434	ollama	LLM service

Step 4: Run Database Migrations

# Enter API container
docker compose exec api sh

# Run migrations
pnpm prisma migrate deploy

# Seed development data (optional)
pnpm prisma:seed

# Exit container
exit

Step 5: Verify Deployment

Check API Health

curl http://localhost:3001/health

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

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

Access Containers

# API container shell
docker compose exec api sh

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

# Redis CLI
docker compose exec valkey redis-cli

Management Commands

Start/Stop Services

# Start all
docker compose up -d

# Stop all
docker compose stop

# Stop and remove containers
docker compose down

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

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart api

View Service Status

# List running containers
docker compose ps

# View resource usage
docker stats

# View logs
docker compose logs -f [service_name]

Rebuild After Code Changes

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

# Rebuild specific service
docker compose build api
docker compose up -d api

Production Deployment

Environment Configuration

Create a production .env file:

# Production database
DATABASE_URL=postgresql://user:pass@prod-db-host:5432/mosaic

# Production Redis
REDIS_URL=redis://prod-redis-host:6379

# Production URLs
NEXT_PUBLIC_APP_URL=https://mosaic.example.com

# Secure JWT secret
JWT_SECRET=$(openssl rand -base64 64)
JWT_EXPIRATION=24h

# Authentik OIDC
OIDC_ISSUER=https://auth.example.com/application/o/mosaic/
OIDC_CLIENT_ID=prod-client-id
OIDC_CLIENT_SECRET=prod-client-secret
OIDC_REDIRECT_URI=https://mosaic.example.com/auth/callback

Compose Override for Production

Create docker-compose.prod.yml:

services:
  api:
    restart: always
    environment:
      NODE_ENV: production
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '1.0'
          memory: 1G

  web:
    restart: always
    environment:
      NODE_ENV: production
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Deploy:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Troubleshooting

Containers Won't Start

# Check logs for errors
docker compose logs api
docker compose logs postgres

# Check container status
docker compose ps

# Restart specific service
docker compose restart api

Database Connection Failed

# Check PostgreSQL is running
docker compose ps postgres

# Check PostgreSQL logs
docker compose logs postgres

# Test connection from API container
docker compose exec api sh
nc -zv postgres 5432

Port Already in Use

# Find what's using the port
lsof -i :3001

# Kill the process or change port in docker-compose.yml

Out of Disk Space

# Remove unused containers/images
docker system prune -a

# Remove unused volumes (WARNING: may delete data)
docker volume prune

Permission Errors

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or
newgrp docker

Monitoring

Resource Usage

# Live resource stats
docker stats

# Container logs
docker compose logs -f --tail=100

Health Checks

# API health endpoint
curl http://localhost:3001/health

# PostgreSQL connection
docker compose exec postgres pg_isready -U mosaic

# Redis ping
docker compose exec valkey redis-cli ping

Updating

Pull Latest Changes

git pull origin develop

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

Update Docker Images

# Pull latest base images
docker compose pull

# Rebuild
docker compose up -d --build

Backup and Restore

Database Backup

# Backup database
docker compose exec postgres pg_dump -U mosaic -d mosaic > backup-$(date +%Y%m%d).sql

# Restore database
cat backup-20260128.sql | docker compose exec -T postgres psql -U mosaic -d mosaic

Volume Backup

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

Next Steps

1. Configure Authentication — Authentik Setup
2. Monitor Logs — Set up log aggregation for production
3. Set up Backups — Automate database backups
4. Configure SSL — Add reverse proxy (Traefik/Nginx) for HTTPS