Skip to main content

RUN A WORKER IN DOCKER

This guide shows you how to run a single Swamp worker inside a Docker container, connected to an orchestrator on your host machine.

For deploying a scalable pool of workers, see Run a Fleet with Docker Compose.

Build the worker image

Compile the Swamp binary and build a Docker image containing it:

swamp compile
docker build -t swamp-worker .

If your project does not include a Dockerfile, create one that copies the compiled binary:

FROM debian:bookworm-slim
COPY swamp /usr/local/bin/swamp
ENTRYPOINT ["swamp"]

Generate a self-signed TLS certificate

The orchestrator requires TLS for off-loopback connections. For local testing, generate a self-signed certificate:

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
  -keyout key.pem -out cert.pem -days 30 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,DNS:host.docker.internal" \
  -addext "basicConstraints=CA:FALSE"

basicConstraints=CA:FALSE is required — without it, the Deno runtime rejects the certificate as a CA certificate used as a server certificate.

Include host.docker.internal in the SAN so the worker can verify the certificate when connecting from inside the container.

Start the orchestrator

Start swamp serve with TLS, token authentication, and the host bound to 0.0.0.0 so the container can reach it:

swamp serve \
  --host 0.0.0.0 \
  --cert-file cert.pem \
  --key-file key.pem \
  --auth-mode token \
  --trusted-hosts host.docker.internal

--trusted-hosts allows the Host: host.docker.internal header that Docker sends. Without it, the orchestrator rejects the connection. See Serve Flags for the full flag reference.

Create tokens

In a separate terminal, create a server token and a worker enrollment token:

swamp auth server-token create admin --duration 24h
swamp worker token create docker-worker --duration 24h

Save both token values — they are shown once.

Run the worker container

docker run -d --name swamp-worker \
  -e SWAMP_ORCHESTRATOR_URL=wss://host.docker.internal:9090 \
  -e SWAMP_SERVER_TOKEN=admin.<secret> \
  -e SWAMP_WORKER_TOKEN=docker-worker.<secret> \
  -e SWAMP_WORKER_LABELS=env=docker \
  -e DENO_CERT=/certs/cert.pem \
  -v "$(pwd)/cert.pem:/certs/cert.pem:ro" \
  swamp-worker worker connect

DENO_CERT is a Deno runtime setting that trusts the self-signed CA certificate. It is not a Swamp flag. The certificate file is bind-mounted into the container.

Refer to Worker Commands for the full list of environment variables and flags.

Verify enrollment

Confirm the worker appears in the pool:

swamp worker list

The worker should show as connected with the env=docker label.

Run a placed workflow

Create a workflow that targets the Docker worker by label and run it:

jobs:
  - name: test
    steps:
      - name: hello
        task:
          type: model_method
          modelIdOrName: my-model
          methodName: run
        labels:
          env: docker
swamp workflow run my-workflow

The step dispatches to the Docker worker. Confirm completion with swamp workflow status my-workflow.

← PreviousWorker FleetsNext →Run a Fleet with Docker Compose