Savannah Cloud Docs

Prerequisites

Tool	Version
Docker Desktop / Docker Engine	24+
Docker Compose plugin	v2+
Go	1.25+ (local dev without Docker)
Node.js	18+ (local dashboard dev)

1. Clone the Repository

git clone https://github.com/Mbuthia71/distributed-task-queue.git
cd distributed-task-queue

2. Create `.env`

# Linux / WSL / macOS
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
echo "RESEND_API_KEY=re_..." >> .env
echo "AT_API_KEY=atsk_..." >> .env
echo "AT_USERNAME=your_at_username" >> .env

# PowerShell
"JWT_SECRET=$([Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 })))" | Out-File .env

Minimum required keys for full functionality:

Variable	Purpose
`JWT_SECRET`	Signs all JWTs — use a long random string
`RESEND_API_KEY`	Enables email sending via Resend
`AT_API_KEY`	Africa's Talking — enables SMS
`AT_USERNAME`	Africa's Talking username

DATABASE_URL and REDIS_URL are set automatically by Docker Compose.

3. Start All 5 Services

docker compose up -d --build

Container	Role	Port
`riftcloud-app-1`	Go API + Worker pool	`8080`
`riftcloud-dashboard-1`	React UI (Nginx)	`80`
`riftcloud-postgres-1`	PostgreSQL 16	`5432`
`riftcloud-redis-1`	Redis 7	`6379`
`riftcloud-pdns-1`	PowerDNS Auth 4.9	`53`, `8081`

Never rebuild the postgres container unless you intend to wipe data. Use --build app or --build dashboard specifically.

4. Verify Everything is Up

# API health — expects postgres and redis both "ok"
curl http://localhost:8080/health
# → {"status":"ok","postgres":"ok","redis":"ok"}

# Prometheus metrics
curl http://localhost:8080/metrics

# All container statuses
docker compose ps

5. Register Your First Account

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"org_name":"My Org","email":"me@example.com","password":"secret123"}'

Returns { token, user, org }. Save the token.

6. Create an API Key

curl -X POST http://localhost:8080/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-key"}'

Copy the raw_key — it starts with sc_ and is shown once only.

7. Push Your First Job

curl -X POST http://localhost:8080/jobs \
  -H "X-API-Key: sc_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send_email",
    "payload": {"to": "user@example.com", "subject": "Hello", "body": "From Savannah Cloud"},
    "max_retries": 3
  }'

8. Open the Dashboard

Navigate to http://localhost:80 and sign in with your credentials. The dashboard shows live job status via WebSocket.

Common Commands

# Rebuild after code changes (preserves postgres data)
docker compose up -d --build app dashboard

# Stop all services
docker compose down

# Wipe all data (fresh start)
docker compose down -v

# Live logs
docker compose logs -f app