• English

      • Environment Variable Reference

      The API and Worker both read runtime configuration from environment variables. With Docker Compose, Helm, or another container platform, inject these values into the matching container.

      For a first deployment, configure the Basic values only. Once the platform is running, adjust Advanced values when a real requirement appears instead of setting every option up front.

      API Settings

      TypeKeyDefaultPurpose and when to change
      BasicAPP_ENVproductionRuntime mode; set development explicitly only for local development.
      BasicSECRET_ENCRYPTION_KEYEmptySecret encryption key; required and stable in production.
      BasicDATABASE_URLpostgres://devops:devops@postgres:5432/devops?sslmode=disablePostgreSQL URL; change when using another database or credential.
      BasicREDIS_ADDRredis://localhost:6379/0Complete Redis URI in the form redis://username:password@host:port/database; use rediss:// for TLS. Username, password, and DB are no longer configured separately.
      BasicPUBLIC_BASE_URLhttp://localhost:8088Public platform URL; change for public domain, HTTPS, or reverse proxy. OIDC Redirect URI is generated as {PUBLIC_BASE_URL}/api/v1/auth/oidc/callback.
      AdvancedAPI_ADDR:8080API listen address; change for custom container ports.
      AdvancedAPP_CORS_ORIGINShttp://localhost:8088Allowed frontend origins; change when frontend and API use different origins.
      AdvancedTRUSTED_PROXY_CIDRSEmptyReverse-proxy CIDRs allowed to provide the real client address, comma-separated. No proxy is trusted by default. Configure only controlled proxies so a forged X-Forwarded-For cannot bypass per-IP rate limits.
      AdvancedLOG_LEVELinfoLog level; temporarily use debug for local troubleshooting.
      AdvancedDB_MAX_OPEN_CONNS20Maximum PostgreSQL connections opened by this API process; size it across all API and worker replicas to avoid exhausting the database.
      AdvancedDB_MAX_IDLE_CONNS5Idle PostgreSQL connections kept by this API process; lower it when database connections are tight.
      AdvancedDB_CONN_MAX_LIFETIME30mMaximum lifetime of a reused database connection; shorten it for load balancers, connection proxies, or database rolling maintenance.
      AdvancedDB_CONN_MAX_IDLE_TIME5mMaximum idle time for database connections; shorten it when connection slots are tight.
      AdvancedMETRICS_ENABLEDfalseEnables the dedicated Prometheus metrics listener; disabled by default. When set to true, the API uses :9090 by default.
      AdvancedMETRICS_ADDR:9090Metrics listen address; change only when overriding the API metrics port or bind address.
      AdvancedMETRICS_PATH/metricsPrometheus scrape path; registered only on the dedicated metrics listener.
      AdvancedOTEL_EXPORTER_OTLP_ENDPOINTEmptyOpenTelemetry Collector OTLP HTTP endpoint. Leave empty to disable traces, OTLP metrics, and OTel log export. Use the same endpoint for API, Worker, and Agent.
      AdvancedOTEL_RESOURCE_ATTRIBUTESEmptyAdditional environment or cluster resource attributes as comma-separated key=value pairs.
      AdvancedOTEL_EXPORTER_OTLP_HEADERSEmptyCollector authentication headers. Inject from a Secret in production instead of storing them in public configuration.

      When metrics are enabled, only the API exposes a dedicated Prometheus-compatible listener with API HTTP, connection-pool, and dependency-health metrics. Worker and Agent do not expose separate metrics ports; task, queue, build, release, model, and tool metrics flow through OTLP to the unified metrics backend. Grafana dashboard JSON lives under grafana/dashboards/ and can be imported when needed.

      When OTEL_EXPORTER_OTLP_ENDPOINT is configured, the API, Worker, and Agent report traces, metrics, and structured logs through OpenTelemetry. See Connect an Observability Backend for the minimal setup and local verification.

      Before listening on its HTTP port, the API performs one real connection check against both Redis and PostgreSQL. The process exits immediately when either dependency is unreachable, authentication fails, or a PostgreSQL migration fails; it never starts in a partially available state. After startup, go-redis and the database/sql pool recover from transient connection interruptions, while the container platform is responsible for restarting a process whose startup check fails.

      OIDC identity provider Redirect URI is generated from PUBLIC_BASE_URL, and the admin identity provider form shows a copyable value. Admission policy requires OIDC to return a non-empty email and email_verified=true by default. For trusted internal identity providers that cannot return the standard email_verified claim, disable “Require verified OIDC email” in the admission policy; the platform still requires a non-empty email.

      Before login, the frontend picks the first supported language from the browser language preference list. The supported languages are currently zh-CN and en-US. After login, the account language preference wins and is cached locally so the next page load uses the same language immediately.

      Available access-route domain suffixes, external access schemes, external access ports, and Gateway API defaults are managed on runtime clusters. Different clusters can use different gateway domain suffixes, GatewayClasses, and shared Gateways; the same cluster can also define multiple suffixes. A deployment target's cluster decides which suffixes are selectable, and each access route chooses exactly one suffix for default-domain generation, short-host expansion, and console access links. Set a cluster's external access scheme to https when an outer CDN or reverse proxy already terminates HTTPS; this only changes console display and link targets, does not change internal Gateway listeners, and does not request certificates.

      Frontend Build Settings

      TypeKeyDefaultPurpose and when to change
      AdvancedVITE_DOCS_BASE_URLhttps://luna-devops.liteyuki.orgDocumentation site base URL. Help links on pages such as Billing are generated from it. Set it before building the frontend when the docs site uses another domain or path.

      Worker Settings

      TypeKeyDefaultPurpose and when to change
      BasicAPP_ENVproductionRuntime mode; keep it aligned with API.
      BasicSECRET_ENCRYPTION_KEYEmptyDecrypts saved secrets; must match API.
      BasicDATABASE_URLpostgres://devops:devops@postgres:5432/devops?sslmode=disablePostgreSQL URL; point to the same database as API.
      BasicREDIS_ADDRredis://localhost:6379/0Complete Redis URI; use the same URI as API. Use rediss:// for TLS.
      BasicBUILD_EXECUTOR_IMAGEmoby/buildkit:v0.24.0-rootlessBuildKit image; change when the build cluster cannot pull the default image.
      AdvancedLOG_LEVELinfoLog level; temporarily use debug for local troubleshooting.
      AdvancedDB_MAX_OPEN_CONNS20Maximum PostgreSQL connections opened by this worker process; size it across all API and worker replicas to avoid exhausting the database.
      AdvancedDB_MAX_IDLE_CONNS5Idle PostgreSQL connections kept by this worker process; lower it when database connections are tight.
      AdvancedDB_CONN_MAX_LIFETIME30mMaximum lifetime of a reused database connection; shorten it for load balancers, connection proxies, or database rolling maintenance.
      AdvancedDB_CONN_MAX_IDLE_TIME5mMaximum idle time for database connections; shorten it when connection slots are tight.
      AdvancedDEPLOY_ROLLOUT_TIMEOUT_SECONDS600Release wait timeout; increase for slow-starting apps.
      AdvancedCERT_MANAGER_CLUSTER_ISSUERletsencrypt-http01Certificate Issuer name; change when your cluster uses another name.
      AdvancedBUILD_EGRESS_MODErestrictedBuild egress mode. The default allows DNS, public HTTP(S), and configured private sources only. Use permissive only when you explicitly accept that builds can reach arbitrary services in the cluster.
      AdvancedBUILD_JOB_TIMEOUT_SECONDS1800Build timeout fallback used when a deployment target does not set one; increase for large projects.
      AdvancedBUILD_JOB_TTL_SECONDS3600Completed build Pod retention; increase for a longer log window.
      AdvancedBUILD_CACHE_ENABLEDfalseBuild cache switch; enable for faster repeated builds.
      AdvancedBUILD_CACHE_TAGbuildcacheBuild cache tag; change to isolate cache.
      AdvancedBUILD_NPM_REGISTRYEmptynpm registry; set when using an internal mirror.
      AdvancedBUILD_PRIVATE_EGRESS_CIDRSEmptyExtra private CIDRs in restricted mode.
      AdvancedBUILD_PRIVATE_EGRESS_PORTS443Private allowlist ports in restricted mode; use ports like 5000 or 8081 for non-standard registries.
      AdvancedBUILD_BLOCKED_EGRESS_CIDRSEmptyExtra blocked CIDRs in restricted mode.

      Worker no longer listens on a separate metrics port. With OTEL_EXPORTER_OTLP_ENDPOINT configured, task, retry, queue depth, queue latency, build/release result and duration, runtime replica, and gateway sync metrics are exported with the other telemetry signals.

      The worker also starts consuming tasks only after both Redis and PostgreSQL pass their startup connection checks. After startup, Asynq, go-redis, and database/sql recover from transient connection interruptions.

      Agent Settings

      TypeVariableDefaultPurpose and when to change it
      AdvancedAI_OBSERVABILITY_CAPTURE_CONTENTfalseWrites redacted model input/output, reasoning summaries, tool arguments, and tool results to trace events and structured logs. Enable it only for a controlled diagnostic window after restricting Tempo/Loki access and retention.
      AdvancedAI_OBSERVABILITY_CAPTURE_DATABASE_SPANSfalseRecords every PostgreSQL query span inside the Agent. It is disabled by default because event persistence otherwise creates many low-value child spans; enable it temporarily for SQL latency or transaction diagnostics.

      These switches affect only the Agent and require OTEL_EXPORTER_OTLP_ENDPOINT to export data remotely. When content capture is enabled, each field is capped at 32 KiB. Tokens, cookies, passwords, API keys, URL credentials, and secret form values are still replaced with [REDACTED]. Restart the Agent after changing database span capture; the setting affects only newly created traces. See Connect an Observability Backend for fields and queries.