Environment Variables Reference

Use this reference to place deployment settings and check which service reads them. It covers the main service settings; workspace variables and job credentials belong in their resource guides. Defaults can come from application configuration, Compose or Helm, so read the scope beside each value rather than assuming one default applies to every deployment.

Choose where to configure it

Do not put persistent integration settings into generated identity output. After changing a value, update the service that consumes it and verify the effective behavior. Merely editing an env file does not change a process that is already running.

API

The API is the primary Go backend serving the REST API, managing authentication, and running background schedulers.

Server

Database

Authentication (Zitadel)

Browser Sessions

A signed-in browser holds an HttpOnly session cookie; the session itself is stored in PostgreSQL. These settings bound how long it lasts. Each is a Go duration such as 30m or 8h; the API refuses to start with a value that is not a positive duration. See Browser Sessions.

Browser sign-in needs HTTPS, or localhost, because the session cookie is Secure. The API logs a warning at startup when STACKWEAVER_APP_URL is plain http on another host.

Storage (S3-compatible)

Redis

The API must use the same REDIS_DB as the orchestrator and the runners, because that is the queue they share. Pointing them at different logical databases is only useful when you deliberately want two isolated sets of services on one Redis, as a development slot does.

Encryption

This key protects the following stored values: workspace and variable-set variables, Ansible credentials, OpenTofu state files in object storage, sensitive OpenTofu output values, and VCS connection tokens in the database. Use the same value across every service that handles this data so they can read each other's ciphertext. The orchestrator also reads it, to decrypt VCS tokens when refreshing OAuth tokens and building clone URLs and to decrypt the signing keys of notification and run-task webhooks. Like the API and the runners, it refuses to start with a missing, too-short, or all-zero key.

The Helm chart provisions a strong ENCRYPTION_KEY automatically into a Kubernetes Secret (preserved across upgrades and uninstall) and injects it into the API, runners, and orchestrator, or you can bring your own - see the Kubernetes guide. Self-hosted agent runners (RUNNER_MODE=agent) receive job artifacts over the API and do not need this platform encryption key.

State files and VCS tokens stored as plaintext remain readable: decryption tolerates plaintext, and each value is re-encrypted on its next write, so no migration step is required.

OIDC Workload Identity

GitHub Integration

For example, in vcs.env:

GITHUB_WEBHOOK_SECRET='example$literal'

Azure DevOps Integration

SSO

Platform administration

A platform administrator manages the installation itself: the OpenTofu versions catalogue, the list of platform administrators, and a read-only list of every organization. See Platform administration for what the role can and cannot do. On Docker Compose these variables go in sso.env; on Kubernetes they come from the chart's platform.* values.

Miscellaneous

Frontend

The frontend is a React SPA built with Vite. Configuration is loaded at runtime via an env.js file that sets values on window.__STACKWEAVER__. The app falls back to import.meta.env.VITE_* build-time variables, and then to hardcoded defaults.

In Kubernetes, the Helm chart generates env.js automatically from the ingress configuration - the frontend image is generic and does not need domain-specific build args. In the standalone Compose bundle, frontend-config writes env.js after identity initialization. Set its VITE_* inputs and re-run the config writer; adding those variables only to the frontend container does not update that file.

Orchestrator

The orchestrator is a background service that assigns pending runs and jobs to runners via a Redis queue.

OpenTofu Runner

The runner picks jobs from the Redis queue and executes OpenTofu plan/apply/destroy operations.

Using an internal OpenTofu mirror

Runs download the OpenTofu version pinned on the workspace the first time they need it, verifying the archive against the checksums published alongside the release. The runner image already bundles one version, so an install that only ever uses that version needs no outbound access at all.

Air-gapped or egress-restricted installs can point both endpoints at an internal mirror by setting TOFU_RELEASES_URL and TOFU_VERSION_INDEX_URL on the API, orchestrator and runner (the Helm chart exposes these as tofu.releasesUrl and tofu.versionIndexUrl). Set both: the first serves the binaries and the second populates the version catalogue, so overriding only one still leaves the other reaching for the internet.

Your mirror must reproduce the upstream layout exactly, because the runner builds these paths itself:

<TOFU_RELEASES_URL>/v<version>/tofu_<version>_linux_<arch>.zip
<TOFU_RELEASES_URL>/v<version>/tofu_<version>_SHA256SUMS

Checksum verification runs against your mirror's own SHA256SUMS file and cannot be turned off, so the mirror must serve that file alongside the archives. A malformed URL in either variable is logged at startup and ignored in favour of the upstream default rather than failing the service.

Ansible Runner

The Ansible runner processes Ansible playbook jobs from the Redis queue.

In agent mode (RUNNER_MODE=agent) the runner talks only to the Stackweaver API, so the Redis, database and storage variables above are not read. It is configured with the variables below instead.

Runner variables that reach runs

Runner services hold platform credentials that user-supplied code must not inherit. Both runner modes construct subprocess environments from the run's variables plus an allowlist. OpenTofu providers, provisioners, inventory plugins, playbooks and Galaxy installs all run code; granting a variable to a runner's jobs grants it to that code.

flowchart LR
    A["Runner service environment"] --> B["Built-in allowlist and explicit passthrough"]
    B --> D["Run subprocess"]
    C["Workspace variables or job credentials"] --> D

A pod-level cloud identity is available to every run on that runner. The database password, Redis/storage credentials, encryption/signing keys and agent token are not inherited through the built-in list.

For additional names, set the variable on the runner service and list it explicitly:

AWS_PROFILE=example-profile
AWS_CONFIG_FILE=/etc/aws/config
STACKWEAVER_RUN_ENV_PASSTHROUGH=AWS_PROFILE,AWS_CONFIG_FILE

The referenced file must also exist in that runner. Names are exact and comma-separated; wildcards are unsupported. For Helm, use the corresponding runner's env and runEnvPassthrough values:

runner:
  env:
    AWS_PROFILE: example-profile
    AWS_CONFIG_FILE: /etc/aws/config
  runEnvPassthrough:
    - AWS_PROFILE
    - AWS_CONFIG_FILE

Use ansibleRunner.env and ansibleRunner.runEnvPassthrough for Ansible. Never list a platform secret. Verify with a harmless diagnostic on an isolated test workload, without printing secrets into logs.

Zitadel (Identity Provider)

Zitadel is configured via its own YAML files and supports env var overrides using the ZITADEL_* prefix. The following are the most relevant variables used in the StackWeaver deployment.

zitadel-init

The zitadel-init container sets up the Zitadel organisation, OIDC apps, and service users. In Docker Compose it writes the generated credentials to .env in your Compose directory. In Kubernetes it runs as a sidecar in the Zitadel pod and patches the K8s Secret directly. In Kubernetes, the STACKWEAVER_NOTIFICATION_MODE, SMTP_*, STACKWEAVER_SELF_REGISTRATION and ZITADEL_ACCESS_TOKEN_LIFETIME variables are set on the post-install/post-upgrade reconcile Job (ZITADEL_INIT_MODE=reconcile), not on the sidecar.

Kubernetes-only variables

These are set by the Helm chart and used by the sidecar for K8s Secret patching and deployment restarts.

Login (custom Stackweaver SPA)

Login is served by the Stackweaver SPA via /login/* routes; the auth proxy in the API container handles all Zitadel session API calls and OIDC endpoint forwarding. The variables below configure the auth proxy.

Environment File Layout (Docker Compose)

When running with Docker Compose, environment variables are split across several files in your Compose directory (the directory that holds docker-compose.yml).