Skip to main content

Local Development

Run the full Sukko stack on your machine using Docker Compose. No Kubernetes required.

Time to complete

~3 minutes

Prerequisites​

  • Docker installed and running
  • The sukko CLI installed (see Quickstart)

Start the Stack​

sukko up

This starts all services:

ServicePortDescription
ws-gateway3000WebSocket reverse proxy
ws-server3005Core message server
provisioning8080Tenant management API
Redpanda9092Kafka-compatible broker
Valkey6379Broadcast bus

Verify​

Check that all services are healthy:

sukko health
sukko status

Common Operations​

View Logs​

# All services
sukko logs

# Specific service
sukko logs --service gateway

Stop the Stack​

sukko down

Force Pull Latest Images​

sukko down && sukko up --pull

Architecture​

The local stack mirrors production:

Client → ws-gateway (:3000) → ws-server (:3005)
                                    ↓
                              Valkey broadcast
                                    ↓
                              ws-server shards → Clients
                                    ↑
                        Redpanda (Kafka) (:9092)
                                    ↑
                            External publishers

The only difference from production:

  • Single instance of each service (no replication)
  • SQLite for provisioning (no PostgreSQL)
  • All services on localhost (no Kubernetes networking)

Customization​

Environment Variables​

Override service configuration by setting env vars before sukko up:

export SUKKO_LICENSE_KEY="your-pro-license-key"
sukko down && sukko up

Message Backend​

The default local setup uses the direct message backend (no Kafka) — zero external dependencies.

The Kafka/Redpanda backend runs on every edition, Community included — no license is required to select it:

sukko config set message-backend kafka
sukko down && sukko up

This starts a local Redpanda broker (Kafka-wire-compatible) under the kafka compose profile and points ws-server at it.

Client publish on the kafka backend needs routing rules

On the kafka backend, client and REST publishes are routed to topics via per-tenant routing rules — a Pro feature. On Community + kafka, publishes without a matching rule are rejected (409 PUBLISH_NOT_ROUTABLE — deliberately, never silently dropped). Community + kafka is the ingest path: your own producers publish to the tenant's Kafka topics and Sukko fans out to clients, with message history and gap recovery included. For client publishing on Community, use the default direct backend.

migrate-dlq​

If upgrading from a release that predates channel topic routing, run migrate-dlq to create the required infrastructure topics for existing active tenants. See the Kubernetes Upgrading guide for full details.

./migrate-dlq --dry-run  # preview without making changes
./migrate-dlq            # create topics

Next Steps​