Savannah Cloud

Running with Docker

Start the full Savannah Cloud stack locally using Docker Compose.

Services in the stack

docker-compose.yml defines the full platform stack:

ServiceImagePortPurpose
appbuilt from Dockerfile8080Go API + worker
consolebuilt from frontend3000TanStack console
postgrespostgres:165432PostgreSQL database
redisredis:76379Redis queue
pdnsPowerDNS Auth8081nameserver and DNS management
ml-servicePython service8001threat detection

First-time setup

# Clone the repo
git clone https://github.com/Mbuthia71/distributed-task-queue.git
cd distributed-task-queue

# Generate env vars
mkdir -p .env
# or create a root .env file with your secrets
# JWT_SECRET, RESEND_API_KEY, AT_API_KEY, AT_USERNAME

# Start the stack
docker compose up -d --build

Generate a secure JWT secret:

# Linux / WSL / macOS
openssl rand -hex 32

# PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 }))

Common commands

# Start all services
docker compose up -d

# Rebuild only app and console after updates
docker compose up -d --build app console

# Stop all services
docker compose down

# Stop and wipe all data
docker compose down -v

# Tail logs
docker compose logs -f app

Never use --build on the Postgres service. That will recreate the database volume and wipe your stored data.


Health checks

# API health
curl http://localhost:8080/health

# Console
curl http://localhost:3000

# Redis
docker compose exec redis redis-cli ping

Success should show:

  • API health returning { "status": "ok" }
  • dashboard route loading on port 3000
  • Redis replying with PONG

Environment variables

Use a root .env file for local secrets. See Environment Variables for the full list.

JWT_SECRET=your-random-secret
DATABASE_URL=postgres://user:pass@postgres:5432/savannah?sslmode=disable
REDIS_URL=redis://redis:6379

Deployment notes

The full stack is designed to run together in Docker for local development, but the production layout differs slightly:

  • API runs behind a reverse proxy and production TLS layer
  • artifact storage is moved to Cloudflare R2
  • DNS is managed through PowerDNS and org-specific nameservers
  • runtime monitoring and rate limiting are enabled by default

See Self-hosting for the production setup path.

On this page