USE A CONFIG FILE

This guide shows you how to move swamp serve configuration into a YAML file so production deployments use a checked-in config instead of long CLI flag chains.

Create the config file

Create .swamp/serve.yaml in your repository:

# .swamp/serve.yaml
port: 8080
grant-reload: auto
trust-proxy: true
hot-reload: true
ws-idle-timeout: "2m"
queue-timeout: "15m"

auth:
  mode: token
  admins:
    - "user:abc-123"

tls:
  cert-file: server.crt
  key-file: server.key

Start the server. It loads .swamp/serve.yaml automatically:

swamp serve

All settings — including authentication and TLS — can be expressed in the config file. Refer to Serve Flags — Supported keys for the full list.

Override config values with CLI flags

A CLI flag overrides the same setting from the config file. To run on a different port without editing the file:

swamp serve --port 9090

The server uses port 9090 even if the config file says port: 8080. CLI flags also override nested config values — --auth-mode oauth overrides auth.mode: token in the file.

Use a non-default config path

To load a config file from a different location:

swamp serve --config /etc/swamp/serve.yaml

An explicit --config path that does not exist is a hard error — the server refuses to start.

Docker Compose

Mount the config file into the container:

# docker-compose.yml
services:
  swamp:
    image: swamp-serve:latest
    volumes:
      - ./repo:/repo
    command:
      - serve
      - --repo-dir=/repo

The config file at /repo/.swamp/serve.yaml is loaded automatically from the mounted repository.

# .swamp/serve.yaml
port: 9090
host: "0.0.0.0"
trust-proxy: true

auth:
  mode: token
  admins:
    - "user:abc-123"

tls:
  cert-file: /certs/server.crt
  key-file: /certs/server.key

trusted-hosts:
  - host.docker.internal

webhooks:
  - route: /hooks/github
    workflow: deploy-on-push
    secret: "@env=WEBHOOK_SECRET"
    scheme: github

systemd

When running as a system daemon, pass --config to daemon enable so the service definition points at the config file:

swamp serve daemon enable --config /etc/swamp/serve.yaml

All settings — including authentication and TLS — live in the config file.

Kubernetes

Store the config file in a ConfigMap and mount it into the pod. Authentication, TLS paths, and operational settings all go in the config file:

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: swamp-serve-config
data:
  serve.yaml: |
    port: 9090
    host: "0.0.0.0"

    auth:
      mode: oauth
      admins:
        - ops-lead
      allowed-collectives:
        - platform-team

    tls:
      cert-file: /certs/tls.crt
      key-file: /certs/tls.key

    grant-reload: auto
    trust-proxy: true
    hot-reload: true
    heartbeat-interval: "30s"
    stale-ttl: "90s"
    reconciliation-interval: "60s"
    queue-timeout: "15m"

    webhooks:
      - route: /hooks/github
        workflow: deploy-on-push
        secret: "@env=WEBHOOK_SECRET"
        scheme: github

Mount the ConfigMap and pass --config. The TLS cert/key file paths in the config point to a Kubernetes Secret mounted as a volume — the config file holds the paths, not the certificates themselves:

# deployment.yaml (container spec excerpt)
containers:
  - name: swamp-serve
    command:
      - swamp
      - serve
      - --config=/config/serve.yaml
    volumeMounts:
      - name: config
        mountPath: /config
        readOnly: true
      - name: tls
        mountPath: /certs
        readOnly: true
volumes:
  - name: config
    configMap:
      name: swamp-serve-config
  - name: tls
    secret:
      secretName: swamp-serve-tls

Updating the ConfigMap and restarting the pods picks up the new config without changing the deployment manifest.

Add webhooks

Webhooks in the config file use structured YAML instead of the CLI's colon-delimited format:

webhooks:
  - route: /hooks/github
    workflow: deploy-on-push
    secret: "@env=GITHUB_WEBHOOK_SECRET"
    scheme: github
  - route: /hooks/linear
    workflow: sync-issues
    secret: "@file=/run/secrets/linear-webhook"
    scheme: linear
  - route: /hooks/stripe
    workflow: billing-events
    secret: "@vault=prod-secrets:stripe-webhook-key"
    scheme: stripe

Refer to Serve Flags — Webhook format in config files for the full field reference, and Webhooks for provider schemes and signature verification.

← PreviousManage Grants with Files Next →Load External Grants at Startup