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"

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

swamp serve --auth-mode token --admins 'user:abc-123' \
  --cert-file server.crt --key-file server.key

Authentication and TLS flags remain on the command line — they are not supported in the config file. Refer to Serve Flags — Flags not available in the config file 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 --auth-mode token --admins 'user:abc-123' \
  --cert-file server.crt --key-file server.key

The server uses port 9090 even if the config file says port: 8080.

Use a non-default config path

To load a config file from a different location:

swamp serve --config /etc/swamp/serve.yaml \
  --auth-mode token --admins 'user:abc-123' \
  --cert-file server.crt --key-file server.key

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
    environment:
      - SWAMP_SERVE_CERT_FILE=/certs/server.crt
      - SWAMP_SERVE_KEY_FILE=/certs/server.key
    command:
      - serve
      - --repo-dir=/repo
      - --auth-mode=token
      - --admins=user:abc-123

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
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 \
  --auth-mode token --admins 'user:ops-team'

The operational flags live in the config file; authentication and TLS stay as CLI flags baked into the service definition.

Kubernetes

Store the config file in a ConfigMap and mount it into the pod:

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: swamp-serve-config
data:
  serve.yaml: |
    port: 9090
    host: "0.0.0.0"
    grant-reload: auto
    trust-proxy: true
    detach-runs: true
    heartbeat-interval: "30s"
    stale-ttl: "90s"
    reconciliation-interval: "60s"
    hot-reload: true
    queue-timeout: "15m"
    webhooks:
      - route: /hooks/github
        workflow: deploy-on-push
        secret: "@env=WEBHOOK_SECRET"
        scheme: github

Mount the ConfigMap and pass --config:

# deployment.yaml (container spec excerpt)
containers:
  - name: swamp-serve
    command:
      - swamp
      - serve
      - --config=/config/serve.yaml
      - --auth-mode=oauth
      - --admins=ops-lead
      - --allowed-collectives=platform-team
      - --cert-file=/certs/tls.crt
      - --key-file=/certs/tls.key
    volumeMounts:
      - name: config
        mountPath: /config
        readOnly: true
volumes:
  - name: config
    configMap:
      name: swamp-serve-config

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

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