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:
| Service | Image | Port | Purpose |
|---|---|---|---|
app | built from Dockerfile | 8080 | Go API + worker |
console | built from frontend | 3000 | TanStack console |
postgres | postgres:16 | 5432 | PostgreSQL database |
redis | redis:7 | 6379 | Redis queue |
pdns | PowerDNS Auth | 8081 | nameserver and DNS management |
ml-service | Python service | 8001 | threat 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 --buildGenerate 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 appNever 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 pingSuccess 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:6379Deployment 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.