Skip to content
Slipwaydocs

Configuration reference

Sources, lowest to highest precedence: built-in defaults, an optional YAML file (SLIPWAY_CONFIG or --config), then SLIPWAY_* environment variables. Unknown keys in the YAML file are errors. Secret-bearing fields are redacted whenever configuration is printed or logged.

General

Section titled “General”
Environment variable YAML key Default Description
SLIPWAY_BASE_URL base_url http://localhost:8080 Public URL: OIDC redirects, webhook URLs, cookies, job-token issuer
SLIPWAY_LISTEN listen :8080 HTTP listen address
SLIPWAY_SESSION_SECRET session_secret required Signs and encrypts session cookies and CSRF tokens
SLIPWAY_MASTER_KEY master_key required Key-encryption key for the local keyring. Losing it loses all secrets
SLIPWAY_SHUTDOWN_TIMEOUT shutdown_timeout 30s Graceful shutdown budget
SLIPWAY_DEV dev false Development conveniences: embedded NATS, local blob dir, text logs, relaxed secret validation. With no database URL, session secret or master key set it falls back to the compose database and to publicly known, deterministic development secrets (a warning is logged at start). Never in production
SLIPWAY_CONFIG Path to the YAML file

Database

Section titled “Database”
Environment variable YAML key Default Description
SLIPWAY_DATABASE_URL database.url Postgres connection URL (the unprivileged application role)
SLIPWAY_DATABASE_MIGRATE_URL database.migrate_url URL used only to run migrations (schema owner). Lets the app connect as the RLS-subject role
SLIPWAY_DATABASE_SYSTEM_URL database.system_url Postgres URL of a role with BYPASSRLS (slipway_system) for the cross-tenant work of the scheduler, reaper, runner authentication and webhook ingress. Required unless database.url itself bypasses RLS
SLIPWAY_DATABASE_ALLOW_BYPASS database.allow_bypass false Start although database.url is a superuser or BYPASSRLS role. Row-level security is then inert; for single-node installs that accept that. A warning is logged on every start
SLIPWAY_DATABASE_APP_ROLE database.app_role slipway_app Role granted DML after migration
SLIPWAY_DATABASE_MIGRATE database.migrate true Run migrations on boot
SLIPWAY_DATABASE_MAX_CONNS, ..._MIN_CONNS database.max_conns, min_conns pgx defaults Pool sizing

Database roles

Section titled “Database roles”

Tenant isolation is enforced by PostgreSQL row-level security, which PostgreSQL does not apply to superusers or roles with BYPASSRLS. Outside --dev the server therefore refuses to start (and /readyz and slipway doctor report a failure) when:

  • database.url connects as a superuser or a BYPASSRLS role (unless database.allow_bypass is set);
  • database.url is an ordinary role but database.system_url is not set (the scheduler would see no rows); or
  • database.system_url does not connect as a BYPASSRLS role.

The compose file and the Helm chart create slipway_app (no superuser, no BYPASSRLS) and slipway_system (BYPASSRLS) and migrate as a separate owner role through database.migrate_url.

Run slipway migrate up as a separate step (as the Helm chart does) when you prefer migrations outside application start.

NATS

Section titled “NATS”
Environment variable YAML key Default Description
SLIPWAY_NATS_URL nats.url JetStream server URL
SLIPWAY_NATS_TOKEN nats.token Token for an external NATS server that requires one (ignored when the URL already carries credentials)
SLIPWAY_NATS_EMBEDDED nats.embedded false In-process NATS (dev, or tiny single-node)
SLIPWAY_NATS_STORE_DIR nats.store_dir temp JetStream directory for the embedded server
SLIPWAY_NATS_REPLICAS nats.replicas 1 Stream replication factor (3 for a clustered production setup)

Object store

Section titled “Object store”
Environment variable YAML key Default Description
SLIPWAY_BLOB_ENDPOINT blob.endpoint S3 endpoint. Empty for AWS S3
SLIPWAY_BLOB_PUBLIC_ENDPOINT blob.public_endpoint = endpoint Browser- and runner-reachable base URL when presigning, if different
SLIPWAY_BLOB_BUCKET blob.bucket slipway Bucket
SLIPWAY_BLOB_REGION blob.region us-east-1 Region
SLIPWAY_BLOB_ACCESS_KEY, ..._SECRET_KEY blob.access_key, secret_key Static credentials. Omit to use the ambient identity (IRSA / Workload Identity)
SLIPWAY_BLOB_PATH_STYLE blob.path_style false Path-style addressing (required for MinIO)
SLIPWAY_BLOB_LOCAL_DIR blob.local_dir Filesystem store instead of S3 (dev only)

Cache

Section titled “Cache”
Environment variable YAML key Description
SLIPWAY_CACHE_URL cache.url redis:// or rediss:// URL for Valkey or Redis

Logging and telemetry

Section titled “Logging and telemetry”
Environment variable YAML key Default Description
SLIPWAY_LOG_LEVEL log.level info debug, info, warn, error
SLIPWAY_LOG_FORMAT log.format json json or text
SLIPWAY_OTEL_EXPORTER otel.exporter none none or otlp (OTLP/HTTP traces and metrics)
SLIPWAY_OTEL_ENDPOINT otel.endpoint OTLP/HTTP base URL; empty uses the standard OTEL_EXPORTER_OTLP_* variables
SLIPWAY_OTEL_SERVICE_NAME otel.service_name slipway Service name
SLIPWAY_OTEL_SAMPLE_RATIO otel.sample_ratio 1 Trace sampling ratio
SLIPWAY_OTEL_PROMETHEUS otel.prometheus true Serve Prometheus metrics at /metrics

Example file

Section titled “Example file”
base_url: https://slipway.example.com
listen: ":8080"
database:
  url: postgres://slipway_app:...@db.internal:5432/slipway?sslmode=require
  migrate_url: postgres://slipway_owner:...@db.internal:5432/slipway?sslmode=require
nats:
  url: nats://nats-0.nats:4222
  replicas: 3
blob:
  bucket: slipway-prod
  region: eu-west-1        # credentials from the environment (IRSA)
cache:
  url: rediss://valkey.internal:6379
log: { level: info, format: json }
otel: { exporter: otlp, endpoint: http://otel-collector:4318 }

Put session_secret and master_key in environment variables, not in the file.

Runner settings

Section titled “Runner settings”

Runners have their own configuration. See the runner configuration reference.