Configuration

Minimum configuration

At a minimum, Qaynaq needs a SECRET_KEY (32-byte encryption key for stored credentials) and a DATABASE_URI (where flows and connections are persisted). Without these, the coordinator will not start. Everything else has a sensible default.

Workers must be started with the exact same SECRET_KEY as the coordinator. Otherwise they cannot decrypt stored credentials and flows will fail at runtime.

Qaynaq supports three configuration methods. When the same setting is specified in multiple places, the precedence is:

1. CLI flags (highest priority)
2. Environment variables
3. YAML configuration file
4. Default values (lowest priority)

YAML Configuration File

Define all settings in a single YAML file and load it with the -config flag:

role: coordinator
grpc-port: 50000
http-port: 8080
discovery-uri: localhost:50000
debug: false

database:
  driver: sqlite
  uri: "file:./qaynaq.sqlite?_foreign_keys=1&mode=rwc"

secret:
  key: "this_is_a_32_byte_key_for_AES!!!"

auth:
  type: none

./qaynaq -config config.yaml

A complete example is available in the repository at config.example.yaml.

CLI flags and environment variables override YAML values. For example, this starts a worker regardless of what the YAML file says:

./qaynaq -config config.yaml -role worker -grpc-port 50001

Environment Variable Interpolation

YAML values support ${VAR} interpolation, allowing you to reference environment variables directly in the config file. Use ${VAR:-default} to provide a fallback when the variable is not set:

database:
  driver: "${DB_DRIVER:-postgres}"
  uri: "postgres://${PG_USER:-qaynaq}:${PG_PASS}@${PG_HOST:-localhost}:${PG_PORT:-5432}/${PG_DB:-qaynaq}?sslmode=disable"

secret:
  key: "${SECRET_KEY}"

This is especially useful for keeping sensitive values out of config files while still having a complete, shareable configuration template.

Docker with YAML Config

Mount a config file into the container and reference it in the command:

docker run -d --name qaynaq-coordinator \
  -p 8080:8080 -p 50000:50000 \
  -v qaynaq-data:/data \
  -v ./config.yaml:/etc/qaynaq/config.yaml \
  ghcr.io/qaynaq/qaynaq -config /etc/qaynaq/config.yaml

You can still override specific values with environment variables:

docker run -d --name qaynaq-coordinator \
  -p 8080:8080 -p 50000:50000 \
  -e SECRET_KEY="production-secret-key-here!!!!" \
  -v qaynaq-data:/data \
  -v ./config.yaml:/etc/qaynaq/config.yaml \
  ghcr.io/qaynaq/qaynaq -config /etc/qaynaq/config.yaml

Environment Variables

All settings can also be configured through environment variables without a YAML file:

export DATABASE_DRIVER="sqlite"
export DATABASE_URI="file:./qaynaq.sqlite?_foreign_keys=1&mode=rwc"
export SECRET_KEY="this_is_a_32_byte_key_for_AES!!!"
./qaynaq -role coordinator -grpc-port 50000

Database

SQLite

database:
  driver: sqlite
  uri: "file:./qaynaq.sqlite?_foreign_keys=1&mode=rwc"

Or via environment variables:

export DATABASE_DRIVER="sqlite"
export DATABASE_URI="file:./qaynaq.sqlite?_foreign_keys=1&mode=rwc"

PostgreSQL

database:
  driver: postgres
  uri: "postgres://${PG_USER:-qaynaq}:${PG_PASS}@${PG_HOST:-localhost}:5432/${PG_DB:-qaynaq}?sslmode=disable"

Or via environment variables:

export DATABASE_DRIVER="postgres"
export DATABASE_URI="postgres://qaynaq:yourpassword@localhost:5432/qaynaq?sslmode=disable"

tip

For production PostgreSQL deployments, use sslmode=require or sslmode=verify-full and secure credentials.

Secret Key

A 32-byte encryption key is required for storing secrets:

secret:
  key: "this_is_a_32_byte_key_for_AES!!!"

All Settings

Flag	Env Var	YAML Key	Default	Description
-role	ROLE	role	coordinator	Node role (coordinator or worker)
-grpc-port	GRPC_PORT	grpc-port	50000	gRPC port for coordinator-worker communication
-http-port	HTTP_PORT	http-port	8080	HTTP port for web UI and API
-discovery-uri	DISCOVERY_URI	discovery-uri	localhost:50000	Coordinator address for workers
-debug	DEBUG_MODE	debug	false	Enable debug logging
--database.driver	DATABASE_DRIVER	database.driver	sqlite	Database driver
--database.uri	DATABASE_URI	database.uri	—	Database URI (required for coordinator)
--secret.key	SECRET_KEY	secret.key	—	Encryption key (required, 32 bytes)
--auth.type	AUTH_TYPE	auth.type	none	Auth type: none, basic, or oauth2
--auth.basic-username	AUTH_BASIC_USERNAME	auth.basic-username	—	Basic auth username
--auth.basic-password	AUTH_BASIC_PASSWORD	auth.basic-password	—	Basic auth password

See Keycloak Authentication for OAuth2 settings.

Running Multiple Nodes

When running both coordinator and worker on the same host, use different gRPC ports:

# Coordinator
./qaynaq -config config.yaml -role coordinator -grpc-port 50000

# Worker
./qaynaq -config config.yaml -role worker -grpc-port 50001

Or use separate YAML files for each role.