Savannah Cloud

Quickstart

Get Savannah Cloud running locally with Docker and start deploying apps.

Prerequisites

ToolVersion
Docker Desktop / Docker Engine24+
Docker Compose pluginv2+
Go1.25+ (local dev without Docker)
Node.js18+ (dashboard development)

1. Clone the repository

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

2. Set environment variables

Create a .env file at the project root with the required values.

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

For the full reference, see Environment Variables.

3. Start the stack

docker compose up -d --build

This starts the full platform:

ServicePurposePort
appGo API + worker8080
consoleTanStack console3000
postgresPostgreSQL 165432
redisRedis queue6379
pdnsPowerDNS8081
ml-servicethreat detection service8001

4. Verify the environment

curl http://localhost:8080/health
curl http://localhost:3000

You should see a healthy API response and the dashboard root page.

5. Create an org and 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"
  }'

This returns a JWT token you can reuse for authenticated requests.

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":"ci-pipeline"}'

Save the raw key value immediately; it is only shown once.

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 '{
    "ID": "job-001",
    "Type": "send_email",
    "Payload": {
      "to": "user@example.com",
      "subject": "Hello from Savannah Cloud"
    },
    "MaxRetries": 3
  }'

8. Open the dashboard

Go to:

Use the console to inspect deployments, domains, jobs, usage, and billing data.

Next steps

Never run --build against the Postgres service in local Docker; rebuild only the app and console services to avoid destroying your data volume.

On this page