Skip to content
Forgeplane Docs

Forgeplane configuration reference

Forgeplane reads FORGEPLANE_* environment variables, Helm-rendered deployment values, and coordinator system settings. Use this page to choose the correct configuration layer, understand precedence, and review security-sensitive defaults. It is a curated operator reference, not an exhaustive copy of every setting.

Sources of truth and precedence

Section titled “Sources of truth and precedence”

Use the source that matches how Forgeplane is running:

Source Authority
charts/forgeplane/values.yaml and the chart README Supported values, Secret wiring, and deployment defaults for the packaged Helm release
internal/config/config.go Process environment names, parsing, validation, and built-in defaults
/admin/settings and System Settings Runtime-tunable settings stored by the coordinator

At runtime, precedence is:

  1. A supported database-backed system setting, where one exists
  2. An explicitly supplied FORGEPLANE_* environment variable
  3. The built-in process default

Do not copy a process default into deployment automation without checking the installed Helm chart and release-specific configuration. A value that is safe for local development may not be a production recommendation.

Helm values are not a fourth runtime layer: the chart renders values and Kubernetes Secrets into process configuration. The chart can intentionally choose production defaults that differ from the bare process defaults, so deployed Helm behavior must be read from the chart version you install.

For workers, use workerDefaults.* for shared chart configuration and workerPools.<name>.* for named pool overrides.

Required security material

Section titled “Required security material”

Supply secrets through your platform’s secret store. Do not commit them to values files or container images.

Variable Requirement
FORGEPLANE_JWT_SECRET Required by the coordinator for session signing; empty and known development defaults are rejected
FORGEPLANE_SECRET_KEY Required 32-byte key for encryption of sensitive coordinator data
FORGEPLANE_WORKER_ENROLLMENT_TOKEN Shared enrollment authority used when workers register
FORGEPLANE_REAPER_AUTH_KEY Optional dedicated, restart-stable key for workspace/spool ownership manifests; otherwise deployment-held secret material is used
FORGEPLANE_NATS_RELAY_SIGNING_SECRET Optional HMAC key for logs.run.* relay messages
FORGEPLANE_NATS_RUN_EVENT_SIGNING_SECRET Optional HMAC key for runs.status messages

Rotating encryption or managed-state keys requires the matching rotation procedure. Replacing a key without preserving referenced key IDs can make encrypted data unrecoverable.

Important process defaults

Section titled “Important process defaults”

These are the current bare-process defaults. They are useful for detecting accidental configuration drift; they are not production recommendations.

Coordinator and PostgreSQL

Section titled “Coordinator and PostgreSQL”
Variable Default Operator note
FORGEPLANE_HTTP_PORT 8080 Product API and UI listener
FORGEPLANE_ADMIN_HTTP_PORT 8082 Dedicated admin/health listener
FORGEPLANE_GRPC_PORT 9090 Worker-facing coordinator listener
FORGEPLANE_GRPC_ALLOW_INSECURE false A server certificate is required unless insecure mode is explicitly enabled
FORGEPLANE_GRPC_REQUIRE_CLIENT_CERT false The production Helm chart enables worker mTLS
FORGEPLANE_HTTP_SUCCESS_LOG_SAMPLE_RATE 0.1 Clamped to 0.0..1.0
FORGEPLANE_URL empty Required when mail delivery needs absolute application links
FORGEPLANE_DB_HOST localhost
FORGEPLANE_DB_PORT 5432
FORGEPLANE_DB_NAME forgeplane
FORGEPLANE_DB_SSLMODE disable Local default; use verified TLS in production
FORGEPLANE_DB_MAX_OPEN_CONNS 25 Budget across the maximum coordinator replica count
FORGEPLANE_DB_MAX_IDLE_CONNS 10 Must not exceed max open connections
FORGEPLANE_DB_CONN_MAX_LIFETIME 5m
FORGEPLANE_DB_CONN_MAX_IDLE_TIME 1m

NATS and transport

Section titled “NATS and transport”
Variable Default
FORGEPLANE_NATS_URL nats://localhost:4222
FORGEPLANE_NATS_TLS_ENABLED true
FORGEPLANE_NATS_AUTH_MODE userpass
FORGEPLANE_NATS_CONSUMER_ACK_WAIT 30s
FORGEPLANE_NATS_CONSUMER_MAX_ACK_PENDING 200
FORGEPLANE_NATS_CONSUMER_MAX_DELIVER 10

The optional FORGEPLANE_NATS_RELAY_* group inherits the primary connection unless a relay value is set. TLS certificate/key pairs must be supplied together. Coordinator gRPC secure mode requires a server certificate; worker mTLS additionally requires the client CA and client certificate configuration selected by the chart.

Worker runtime

Section titled “Worker runtime”
Variable Default Operator note
FORGEPLANE_COORDINATOR_ADDR localhost:9090 Coordinator gRPC address
FORGEPLANE_WORKER_POOL_NAME default Pool advertised during registration
FORGEPLANE_WORKER_CAPABILITIES none ([]) The base worker bundles no IaC tools; use a tool-enabled image and advertise only its real capabilities
FORGEPLANE_WORKER_HEARTBEAT_INTERVAL 5s
FORGEPLANE_WORKER_HEALTH_PORT 8081 Health listener is enabled by default
FORGEPLANE_WORKER_HEALTH_BIND_ADDRESS empty Binds the listener without a loopback-only restriction
FORGEPLANE_MAX_CONCURRENT_JOBS 1
FORGEPLANE_JOB_TIMEOUT_DEFAULT 30m
FORGEPLANE_JOB_TIMEOUT_MAX 2h
FORGEPLANE_WORKSPACE_SIZE_LIMIT_MB 2048
FORGEPLANE_ARTIFACT_SIZE_LIMIT_MB 512
FORGEPLANE_HTTP_RESOLVER_TIMEOUT 10s
FORGEPLANE_HTTP_RESOLVER_MAX_RESPONSE_BYTES 1048576 1 MiB

Worker capability names are scheduling claims, not tool installers. A worker image must actually contain the binary and supporting runtime it advertises.

Storage and managed state

Section titled “Storage and managed state”
Variable Default
FORGEPLANE_STORAGE_BACKEND local
FORGEPLANE_ARTIFACTS_DIR ./data/blobs
FORGEPLANE_S3_REGION us-east-1
FORGEPLANE_S3_FORCE_PATH_STYLE false
FORGEPLANE_MANAGED_STATE_PLAINTEXT_LIMIT_MB 64
FORGEPLANE_MANAGED_STATE_TRANSFER_MAX_CONCURRENT 2
FORGEPLANE_MANAGED_STATE_TRANSFER_PER_WORKER 1
FORGEPLANE_MANAGED_STATE_RETENTION_DRY_RUN true
FORGEPLANE_MANAGED_STATE_RETENTION_MIN_GENERATIONS 10
FORGEPLANE_MANAGED_STATE_RETENTION_MIN_AGE 8760h (365 days)
FORGEPLANE_MANAGED_STATE_RETENTION_TOMBSTONE_DELAY 720h (30 days)
FORGEPLANE_MANAGED_STATE_RETENTION_BATCH_SIZE 100
FORGEPLANE_MANAGED_STATE_RETENTION_INTERVAL 24h
FORGEPLANE_MANAGED_STATE_ENVELOPE_WRITE_VERSION 1

Envelope versions 1 and 2 are accepted; any other value falls back to 1. Change the write version only as part of the documented envelope rollout. PostgreSQL metadata, encrypted object-storage blobs, and all referenced decrypt keys must be backed up and restored as one recovery set.

Observability

Section titled “Observability”
Variable Default
FORGEPLANE_OTEL_ENABLED false
FORGEPLANE_OTEL_TRACES_ENABLED true
FORGEPLANE_OTEL_METRICS_ENABLED false
FORGEPLANE_OTEL_LOGS_ENABLED false
FORGEPLANE_OTEL_ENDPOINT empty
FORGEPLANE_OTEL_SAMPLING_RATE 0.10
FORGEPLANE_OTEL_TRACE_CONTINUATION_MAX_AGE 15m
FORGEPLANE_OTEL_SERVICE_NAME empty
FORGEPLANE_DEPLOYMENT_ENVIRONMENT empty
FORGEPLANE_OTEL_INSECURE false
FORGEPLANE_PROMETHEUS_METRICS_ENABLED true
FORGEPLANE_METRICS_AUTH_ENABLED false
FORGEPLANE_PROFILING_ENABLED false

The trace, metric, and log switches only take effect when the relevant exporter is enabled. Production validation rejects insecure OTel transport unless FORGEPLANE_OTEL_ALLOW_INSECURE_IN_PROD=true.

Email

Section titled “Email”

Mail delivery is unconfigured while FORGEPLANE_MAIL_SMTP_HOST is empty. When it is configured, FORGEPLANE_MAIL_FROM_ADDRESS is required.

Variable Default
FORGEPLANE_MAIL_SMTP_PORT 587
FORGEPLANE_MAIL_SMTP_AUTH_MODE plain
FORGEPLANE_MAIL_SMTP_SECURITY_MODE starttls_required
FORGEPLANE_MAIL_SMTP_ALLOW_INSECURE_PLAINTEXT false
FORGEPLANE_MAIL_FROM_NAME Forgeplane
FORGEPLANE_MAIL_MAX_ATTEMPTS 3
FORGEPLANE_MAIL_RETRY_BACKOFF 0s,5s,30s

Configuration groups

Section titled “Configuration groups”

Use the implementation or chart reference for the complete set within each group:

  • FORGEPLANE_DB_*: PostgreSQL address, credentials, TLS mode, and pool limits
  • FORGEPLANE_NATS_*: primary and relay connections, TLS, authentication, delivery, and message signing
  • FORGEPLANE_GRPC_* and FORGEPLANE_WORKER_GRPC_*: coordinator server TLS and worker client TLS
  • FORGEPLANE_STORAGE_*, FORGEPLANE_S3_*, and FORGEPLANE_MANAGED_STATE_*: artifact and managed-state persistence
  • FORGEPLANE_OTEL_*, FORGEPLANE_PROMETHEUS_*, FORGEPLANE_METRICS_*, and FORGEPLANE_PROFILING_*: telemetry export and scrape protection
  • FORGEPLANE_MAIL_*: SMTP transport and retry policy
  • FORGEPLANE_WEBHOOK_*: explicit private-target allowlists

Production guardrails

Section titled “Production guardrails”
  • Prefer the chart’s coordinator.existingSecret and external secret integration over plaintext values.
  • Use PostgreSQL verify-full where the certificate and hostname support it.
  • Keep coordinator-worker gRPC encrypted; use worker client certificates for production mTLS.
  • Restrict the admin listener, worker health listeners, readiness detail, and metrics to trusted networks.
  • Keep managed-state retention in dry-run until backups, restore drills, key escrow, and deletion review are in place.
  • Recheck the installed chart values and internal/config/config.go after an upgrade; this curated page deliberately omits low-level and release-specific knobs.