Quickstart
Get Savannah Cloud running locally with Docker and start deploying apps.
Prerequisites
| Tool | Version |
|---|---|
| Docker Desktop / Docker Engine | 24+ |
| Docker Compose plugin | v2+ |
| Go | 1.25+ (local dev without Docker) |
| Node.js | 18+ (dashboard development) |
1. Clone the repository
git clone https://github.com/Mbuthia71/distributed-task-queue.git
cd distributed-task-queue2. 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" >> .envFor the full reference, see Environment Variables.
3. Start the stack
docker compose up -d --buildThis starts the full platform:
| Service | Purpose | Port |
|---|---|---|
app | Go API + worker | 8080 |
console | TanStack console | 3000 |
postgres | PostgreSQL 16 | 5432 |
redis | Redis queue | 6379 |
pdns | PowerDNS | 8081 |
ml-service | threat detection service | 8001 |
4. Verify the environment
curl http://localhost:8080/health
curl http://localhost:3000You 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
Architecture
Understand the platform components and data flow.
API Reference
Read the auth, jobs, usage, and team endpoints.
Docker
Learn the full local Docker workflow.
Self-hosting
Deploy to a VPS in production.
Never run --build against the Postgres service in local Docker; rebuild only the app and console services to avoid destroying your data volume.