Blockyard reads its configuration from a TOML file. The default path is blockyard.toml in the working directory. Override it with the --config CLI argument:

blockyard --config /etc/blockyard/config.toml

Environment variable overrides#

Every configuration field can be set via an environment variable. The naming convention is:

BLOCKYARD_<SECTION>_<FIELD>

All uppercased. For example, [server] bind becomes BLOCKYARD_SERVER_BIND.

Environment variables take precedence over values in the TOML file.

[server]#

[server]
bind             = "127.0.0.1:8080"
shutdown_timeout = "30s"
# backend              = "docker"       # "docker" (default) or "process"
# skip_preflight       = false
# default_memory_limit = "2g"           # fallback per worker; empty = unlimited
# default_cpu_limit    = 4.0            # fallback per worker; 0 = unlimited
# management_bind      = "127.0.0.1:9100"
# log_level            = "info"
# session_secret       = "random-secret"   # required when [oidc] is configured
# external_url         = "https://blockyard.example.com"
# trusted_proxies      = ["10.0.0.0/8"]

server.skip_docker_preflight is deprecated and has been renamed to skip_preflight. The old name is still accepted for one release with a deprecation warning.

API authentication uses Personal Access Tokens (for CLI/CI access) or OIDC session cookies (for browser access). The v0 static bearer token (server.token) has been removed.

[docker]#

Required when [server] backend = "docker" (the default). Configures the Docker/Podman runtime used for worker and build containers.

[docker]
socket          = "/var/run/docker.sock"
image           = "ghcr.io/cynkra/blockyard-worker:4.4.3"
shiny_port      = 3838
pak_version     = "stable"
# service_network  = ""
# runtime          = ""          # OCI runtime; empty = Docker daemon default

In earlier releases default_memory_limit, default_cpu_limit, and store_retention lived in [docker]. They have moved to [server] and [storage] respectively because they are backend-neutral. The old names are still parsed for one release with a deprecation warning.

[process]#

Required when [server] backend = "process". Configures the bubblewrap-based worker sandbox. See the Process Backend (Native) and Process Backend (Containerized) guides for deployment walkthroughs, and Backend Security for the trade-offs compared to the Docker backend.

[process]
bwrap_path             = "/usr/bin/bwrap"
r_path                 = "/usr/bin/R"
# seccomp_profile        = "/etc/blockyard/seccomp.bpf"  # empty = no seccomp
port_range_start       = 10000
port_range_end         = 10999
worker_uid_range_start = 60000
worker_uid_range_end   = 60999
worker_gid             = 65534
# skip_metadata_check    = false

Per-worker resource limits (server.default_memory_limit, server.default_cpu_limit, per-app overrides) are not enforced by the process backend. Setting them produces a preflight warning. Use systemd MemoryMax= / CPUQuota= or the outer container’s cgroups for a shared ceiling.

[storage]#

[storage]
bundle_server_path    = "/data/bundles"
bundle_worker_path    = "/app"
bundle_retention      = 50
max_bundle_size       = 104857600
# soft_delete_retention = "720h"   # 30 days; omit or 0 = immediate hard delete
# store_retention       = "0"      # R library cache eviction; 0 = disabled

# [[storage.data_mounts]]
# name = "datasets"
# path = "/srv/shared/datasets"

[database]#

[database]
driver = "sqlite"
path   = "/data/db/blockyard.db"
# url  = ""   # PostgreSQL connection string (when driver = "postgres")

# Vault-managed Postgres credentials (optional; postgres only):
# vault_mount = "database"
# vault_role  = "blockyard_admin"

Vault-managed Postgres credentials#

When database.vault_role is set, Blockyard obtains its Postgres credentials from the vault database secrets engine on every startup and whenever the cached password stops working. The role’s password is owned by the vault (rotated on the schedule the operator configures on the role), not by the token that created the lease — so Blockyard restarts, deploy pipelines, and token renewals do not affect database access.

One-time operator setup:

1. Create a PostgreSQL role for Blockyard with the privileges it needs (at minimum LOGIN plus CREATE and USAGE on the target database). A typical setup uses a dedicated blockyard_admin role:

   CREATE ROLE blockyard_admin LOGIN PASSWORD '<temp>' CREATEROLE;
   GRANT ALL PRIVILEGES ON DATABASE blockyard TO blockyard_admin;

2. In the vault, register the role as a static-role on the database secrets engine. This tells the vault to adopt the role and manage its password:

   bao write database/static-roles/blockyard_admin \
       db_name=postgresql \
       username=blockyard_admin \
       rotation_period=24h

   The vault immediately rotates the password; subsequent reads of database/static-creds/blockyard_admin return the current one.

3. Grant Blockyard’s AppRole policy read access to the static-creds endpoint:

   path "database/static-creds/blockyard_admin" {
     capabilities = ["read"]
   }

4. Configure Blockyard:

   [database]
   driver     = "postgres"
   url        = "postgres://postgres.internal/blockyard?sslmode=verify-full"
   vault_role = "blockyard_admin"

   The url does not need (and should not include) a username or password — Blockyard injects the vault-issued credentials on every connection.

At runtime, Blockyard re-reads the static-creds endpoint on any Postgres authentication failure, so an out-of-band password rotation heals automatically on the next health poll.

[proxy]#

[proxy]
ws_cache_ttl         = "60s"
health_interval      = "15s"
worker_start_timeout = "60s"
max_workers          = 100
log_retention        = "1h"
# session_idle_ttl     = "0"   # idle timeout for sessions and WebSocket connections; 0 = disabled
idle_worker_timeout  = "5m"
# http_forward_timeout  = "5m"
# max_cpu_limit         = 16.0
# transfer_timeout      = "60s"
# session_max_lifetime  = "0"    # hard cap on session duration; 0 = unlimited

[redis] (optional)#

Enables Redis-backed shared state for the session store, worker registry, and the process backend’s port/UID allocators. Required for rolling updates via by admin update — the old and new server processes use Redis as the cross-process coordination layer. Single-node deployments without rolling updates can omit this section and the in-memory implementation is used.

[redis]
url        = "redis://localhost:6379"
# key_prefix = "blockyard:"

[update] (optional)#

Configures the rolling-update orchestrator driven by by admin update. The orchestrator has two variants, picked automatically based on the configured backend:

• Docker variant — clones the blockyard container next to the old one. Uses only schedule, channel, and watch_period.
• Process variant — forks a new blockyard process on an alternate bind port. Uses schedule, channel, watch_period, plus alt_bind_range and drain_idle_wait. Requires [redis].

See the process backend rolling update walkthrough for the containerized vs. native rules.

[update]
# schedule        = "0 3 * * 0"     # cron; empty = no scheduled updates
# channel         = "stable"        # "stable" or "main"
# watch_period    = "15m"           # post-update health monitoring
# alt_bind_range  = "8090-8099"     # process variant: alternate bind pool
# drain_idle_wait = "5m"            # process variant: session drain timeout

[oidc] (optional)#

Enable OIDC-based authentication. When this section is present, server.session_secret is required unless [vault] is also configured (in which case it can be auto-generated).

[oidc]
issuer_url           = "https://idp.example.com/realms/myapp"
# issuer_discovery_url = ""      # optional: internal URL for OIDC discovery
client_id            = "blockyard"
client_secret        = "oidc-client-secret"
cookie_max_age       = "24h"
initial_admin        = "google-oauth2|abc123"
default_role         = "viewer"

When OIDC is configured, the proxy routes (/app/{name}/) enforce authentication. Users must log in before accessing apps (except for apps with public visibility).

Blockyard requests openid profile email offline_access from the IdP so that long-lived sessions can refresh access tokens without forcing the user to log in again. The IdP must advertise offline_access in scopes_supported and grant it to the client; otherwise the authorize request fails with invalid_scope. For Authentik this means adding the bundled offline_access scope to the provider’s property mappings. Dex grants refresh tokens by default and needs no extra configuration.

Split-URL OIDC#

In Docker or Kubernetes deployments, the OIDC provider (e.g. Dex, Keycloak) is often reachable at a different address from inside the cluster than from the user’s browser. For example:

• Browser reaches the IdP at http://localhost:5556
• Server container reaches the IdP at http://dex:5556 (Docker DNS)

Set issuer_discovery_url to the internal address. Blockyard will:

1. Perform OIDC discovery against the internal URL
2. Route all server-side requests (token exchange, JWKS fetch, refresh) to the internal URL
3. Keep the public issuer_url for browser-facing redirects and token validation

[oidc]
issuer_url           = "http://localhost:5556"       # public: what the browser sees
issuer_discovery_url = "http://dex:5556"             # internal: Docker DNS
client_id            = "blockyard"
client_secret        = "oidc-client-secret"

The corresponding environment variables are BLOCKYARD_OIDC_ISSUER_URL and BLOCKYARD_OIDC_ISSUER_DISCOVERY_URL.

[vault] (optional)#

Enable Vault-compatible credential management. Requires [oidc] to also be configured.

[vault]
address            = "http://openbao:8200"
role_id            = "blockyard-server"          # AppRole role identifier (recommended)
# admin_token      = "vault-admin-token"         # deprecated: use role_id instead
token_ttl          = "1h"
jwt_auth_path      = "jwt"
# secret_id_file    = "/run/secrets/vault_secret_id"   # opt-in: re-read secret_id on each login for rotation
# secret_id_wrapped = true                             # opt-in: secret_id_file holds a response-wrap token to unwrap at login

With AppRole auth (role_id), Blockyard logs in against the vault and re-logs in shortly before each token expires; a 403 on any admin call also triggers an immediate re-login and retry. Point secret_id_file at a path written by Vault Agent (or any rotation tool) to rotate the secret_id without restarting the server. When no file is configured, the secret_id is read once from BLOCKYARD_VAULT_SECRET_ID at startup. session_secret is also auto-generated and stored in vault.

admin_token and role_id are mutually exclusive — setting both is a configuration error.

[[vault.services]]#

Define third-party services whose API keys users can enroll via the vault. Each entry must have id and label. Service IDs must be unique.

Credentials are stored at secret/data/users/{sub}/apikeys/{id}.

[[vault.services]]
id    = "openai"
label = "OpenAI"

[board_storage] (optional)#

Enable board storage via PostgREST. Requires database.driver = "postgres" and [vault] (for vault Identity OIDC tokens that PostgREST uses to enforce row-level security).

[board_storage]
postgrest_url = "http://postgrest:3000"

When configured, workers receive a POSTGREST_URL environment variable pointing to this URL, allowing Shiny apps to store and retrieve board state.

[audit] (optional)#

Enable append-only audit logging to a JSONL file.

[audit]
path = "/data/audit/blockyard.jsonl"

[telemetry] (optional)#

Enable observability features: Prometheus metrics and OpenTelemetry tracing.

[telemetry]
metrics_enabled = true
otlp_endpoint   = "http://otel-collector:4317"

Vault references#

Any secret field in the configuration can reference a value stored in the vault instead of containing the literal secret. Use the vault: prefix:

[oidc]
client_secret = "vault:secret/data/blockyard/oidc#client_secret"

Format: vault:{kv_v2_data_path}#{key}

• {kv_v2_data_path} — the full KV v2 data path (e.g. secret/data/blockyard/oidc)
• {key} — the JSON key within the secret’s data map

At startup, blockyard resolves all vault references before initializing other subsystems. If a reference cannot be resolved (vault unreachable, path missing, key missing), the server exits with a clear error naming the field and path.

Values without the vault: prefix are treated as literals, unchanged from current behavior.