Appearance
Environment Variables
Complete reference for every environment variable used across the Gatez platform. Variables are grouped by service. Defaults are sourced from docker-compose.yml, .env.example, and from_env() / std::env::var() patterns in service source code.
.env File Variables
These variables are defined in .env (copied from .env.example) and referenced by docker-compose.yml:
| Variable | Default | Required | Description |
|---|---|---|---|
GATEZ_ENV | local | No | Environment mode: local, staging, or production. Controls logging level, secret validation, and startup behavior. In production, services refuse to start with default passwords. |
ZITADEL_ADMIN | admin | No | Zitadel admin console username |
ZITADEL_ADMIN_PASSWORD | changeme | No | Zitadel admin console password |
CLICKHOUSE_PASSWORD | changeme | No | ClickHouse default user password |
GF_SECURITY_ADMIN_PASSWORD | admin | No | Grafana admin console password |
LITELLM_MASTER_KEY | sk-local-dev-key | Yes | Master API key for AI Gateway authentication |
OPENAI_API_KEY | (empty) | No | OpenAI API key; enables gpt-4o and gpt-4o-mini models |
ANTHROPIC_API_KEY | (empty) | No | Anthropic API key; enables claude-sonnet model |
GEMINI_API_KEY | (empty) | No | Google Gemini API key; enables gemini-flash model |
GROQ_API_KEY | (empty) | No | Groq API key; enables Groq models |
MISTRAL_API_KEY | (empty) | No | Mistral API key; enables Mistral models |
DEEPSEEK_API_KEY | (empty) | No | DeepSeek API key; enables DeepSeek models |
TOGETHER_API_KEY | (empty) | No | Together AI API key; enables Together models |
COHERE_API_KEY | (empty) | No | Cohere API key; enables Cohere models |
FIREWORKS_API_KEY | (empty) | No | Fireworks API key; enables Fireworks models |
AZURE_OPENAI_API_KEY | (empty) | No | Azure OpenAI API key; enables Azure-hosted OpenAI models |
AZURE_OPENAI_BASE_URL | (empty) | No | Azure OpenAI base URL; required when using Azure OpenAI |
VLLM_BASE_URL | (empty) | No | vLLM base URL; enables self-hosted vLLM models |
MODEL_ALIASES | (empty) | No | Model alias configuration; maps custom names to provider models |
REDIS_URL | redis://redis:6379 | No | Redis connection URL (used as base reference) |
REDIS_PASSWORD | gatez-redis-dev | Yes | Redis authentication password; required for APISIX rate limiting plugins |
APISIX_ADMIN_KEY | edd1c9f034335f136f87ad84b625c8f1 | No | APISIX Admin API authentication key |
DOMAIN | gatez.dev | No | Base domain for production deployment. Used by Caddy for TLS certificates and by portal Dockerfiles for Zitadel/API URLs. |
Portal Build Args (Docker only)
These are Docker build arguments passed during docker build for the operator and developer portals. They are baked into the JS bundle at build time and cannot be changed at runtime.
| Variable | Default | Description |
|---|---|---|
VITE_ZITADEL_URL | (empty) | Zitadel base URL for SSO login. When empty, portals run in dev mock mode (no auth). Example: https://zitadel.gatez.dev |
VITE_ZITADEL_ORG | gateway | Zitadel organization name |
VITE_API_URL | (empty) | Control Plane API base URL. All apiFetch() calls prepend this. Leave empty for production — portals use same-origin requests via nginx proxy to CP-API, keeping api.gatez.dev exclusively for APISIX external API traffic. |
CSP_ZITADEL_ORIGIN | (empty) | Content Security Policy origin for Zitadel. Set at runtime via Docker environment variable. |
WARNING
Portal build args are set during docker build, not at container runtime. Changing VITE_ZITADEL_URL requires rebuilding the portal image. This is a Vite limitation — import.meta.env values are replaced at build time.
DANGER
Change KEYCLOAK_ADMIN_PASSWORD, GF_SECURITY_ADMIN_PASSWORD, REDIS_PASSWORD, LITELLM_MASTER_KEY, and APISIX_ADMIN_KEY from their defaults before any production deployment. Never commit .env to version control.
etcd
| Variable | Default | Required | Description |
|---|---|---|---|
| (configured via CLI flags) | -- | -- | etcd is configured with command-line arguments in docker-compose.yml, not environment variables |
Relevant CLI flags: --advertise-client-urls=http://etcd:2379, --listen-client-urls=http://0.0.0.0:2379, --data-dir=/etcd-data.
APISIX (L1 - API Gateway)
APISIX is configured via layers/api-gateway/config/apisix.yaml mounted into the container. It does not use environment variables directly. The APISIX Admin API key is set in the YAML config file.
| Configuration | Value | Location |
|---|---|---|
| Admin API key | edd1c9f034335f136f87ad84b625c8f1 | apisix.yaml and .env (APISIX_ADMIN_KEY) |
| etcd host | http://etcd:2379 | apisix.yaml |
| Proxy listen port | 9080 | apisix.yaml |
| Admin listen port | 9180 | apisix.yaml |
Redis
| Variable | Default | Required | Description |
|---|---|---|---|
| (configured via CLI flags) | -- | -- | Redis is configured with command-line arguments |
Relevant CLI flags: --maxmemory 512mb, --maxmemory-policy allkeys-lru, --save "", --appendonly no.
External port: 6380 (mapped from internal 6379).
Zitadel
| Variable | Default | Required | Description |
|---|---|---|---|
ZITADEL_ADMIN | admin | No | Admin console username |
ZITADEL_ADMIN_PASSWORD | changeme | No | Admin console password |
ZITADEL_EXTERNALSECURE | false | No | Disable TLS requirement (required for local dev) |
ZITADEL_EXTERNALPORT | 8085 | No | External port for Zitadel |
Zitadel CLI flags: start-from-init --masterkey "MasterkeyNeedsToHave32Chars".
External port: 8085 (mapped from internal 8080). Health endpoint: /debug/healthz.
ClickHouse
| Variable | Default | Required | Description |
|---|---|---|---|
CLICKHOUSE_DB | gateway | No | Default database name, created on startup |
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT | 1 | No | Enable SQL-driven access management |
External ports: 8123 (HTTP), 9000 (native), 9363 (Prometheus metrics).
Qdrant
Qdrant uses default configuration. No environment variables are set in docker-compose.yml.
External ports: 6333 (HTTP/REST), 6334 (gRPC).
AI Gateway (L2)
Source: layers/ai-gateway/src/config.rs GatewayConfig::from_env().
| Variable | Default | Required | Description |
|---|---|---|---|
PORT | 4000 | No | HTTP listen port |
REDIS_URL | redis://redis:6379 | No | Redis connection URL for caching and rate limits |
QDRANT_URL | http://qdrant:6334 | No | Qdrant vector DB URL for semantic cache |
CLICKHOUSE_URL | http://clickhouse:8123 | No | ClickHouse HTTP URL for logging |
OTEL_EXPORTER_OTLP_ENDPOINT | http://otel-collector:4317 | No | OpenTelemetry Collector gRPC endpoint |
OTEL_SERVICE_NAME | ai-gateway | No | Service name for OTel traces and metrics |
OTEL_RESOURCE_ATTRIBUTES | service.name=ai-gateway | No | OTel resource attributes |
OPENAI_API_KEY | (empty) | No | OpenAI API key; enables gpt-4o, gpt-4o-mini |
ANTHROPIC_API_KEY | (empty) | No | Anthropic API key; enables claude-sonnet |
GEMINI_API_KEY | (empty) | No | Google Gemini API key; enables gemini-flash |
GROQ_API_KEY | (empty) | No | Groq API key; enables Groq models |
MISTRAL_API_KEY | (empty) | No | Mistral API key; enables Mistral models |
DEEPSEEK_API_KEY | (empty) | No | DeepSeek API key; enables DeepSeek models |
TOGETHER_API_KEY | (empty) | No | Together AI API key; enables Together models |
COHERE_API_KEY | (empty) | No | Cohere API key; enables Cohere models |
FIREWORKS_API_KEY | (empty) | No | Fireworks API key; enables Fireworks models |
AZURE_OPENAI_API_KEY | (empty) | No | Azure OpenAI API key; enables Azure-hosted OpenAI models |
AZURE_OPENAI_BASE_URL | (empty) | No | Azure OpenAI base URL; required when using Azure OpenAI |
VLLM_BASE_URL | (empty) | No | vLLM base URL; enables self-hosted vLLM models |
MODEL_ALIASES | (empty) | No | Model alias configuration; maps custom names to provider models |
OLLAMA_BASE_URL | http://host.docker.internal:11434 | No | Ollama base URL for local LLM (always enabled) |
LITELLM_MASTER_KEY | (none) | Yes | Master API key; gateway refuses to start if empty |
CACHE_TTL_SECS | 3600 | No | Cache entry time-to-live in seconds |
SEMANTIC_CACHE_ENABLED | false | No | Enable Qdrant-based semantic similarity cache |
SIMILARITY_THRESHOLD | 0.95 | No | Cosine similarity threshold for cache hits (0.0-1.0) |
PII_REDACTION_ENABLED | true | No | Enable PII scanning before LLM calls |
ZITADEL_JWKS_URL | http://gw-zitadel:8080/oauth/v2/keys | No | Zitadel JWKS endpoint for JWT signature verification. Used for offline RS256 validation (no introspection). Cache refreshes every 5 minutes. |
ZITADEL_URL | http://gw-zitadel:8080 | No | Zitadel base URL for token introspection (fallback when JWKS unavailable) |
ZITADEL_CLIENT_ID | apisix-client | No | Zitadel client ID for token introspection |
ZITADEL_CLIENT_SECRET | apisix-client-secret | No | Zitadel client secret for token introspection |
RUST_LOG | ai_gateway=info | No | Rust log level filter |
RUST_TLS_CERT | (empty) | No | Path to TLS certificate file; when set, enables HTTPS instead of HTTP |
RUST_TLS_KEY | (empty) | No | Path to TLS private key file; required when RUST_TLS_CERT is set |
RUST_TLS_CA | (empty) | No | Path to CA certificate for client verification; enables mTLS when set |
GUARD_ENABLED | false | No | Enable multi-layer prompt guard pipeline (regex + webhook). When enabled, all chat completions are scanned before reaching the LLM. |
GUARD_WEBHOOK_URL | (empty) | No | External webhook URL for custom prompt guard. Receives POST with prompt, returns {"action":"reject"} to block. |
GUARD_WEBHOOK_TIMEOUT_MS | 5000 | No | Timeout for guard webhook calls in milliseconds |
OBSERVABILITY_WEBHOOK_ENABLED | false | No | Enable LLM event webhook (sends batched events to external observability tool like Langfuse/LangSmith) |
OBSERVABILITY_WEBHOOK_URL | (empty) | No | Webhook URL for LLM observability events. Receives batched POST with model, tokens, latency, cache_hit. |
LANGFUSE_HOST | (empty) | No | Langfuse host URL for native observability export. When set with PUBLIC_KEY and SECRET_KEY, enables automatic generation-level trace export to Langfuse. Example: https://cloud.langfuse.com or self-hosted instance. |
LANGFUSE_PUBLIC_KEY | (empty) | No | Langfuse public API key for authentication. Required when LANGFUSE_HOST is set. |
LANGFUSE_SECRET_KEY | (empty) | No | Langfuse secret API key for authentication. Required when LANGFUSE_HOST is set. Never log or expose in responses. |
LANGSMITH_API_KEY | (empty) | No | LangSmith API key for native observability export. When set, enables automatic run-level trace export to LangSmith (LangChain). Format: lsv2_*. |
LANGSMITH_ENDPOINT | https://api.smith.langchain.com | No | LangSmith API endpoint. Defaults to LangChain's hosted service. Override for self-hosted LangSmith instances. |
LANGSMITH_PROJECT | gatez | No | LangSmith project name for grouping traces. All LLM events are tagged with this project. |
CONFIG_WATCH_PATHS | (empty) | No | Comma-separated file paths to watch for changes. Triggers hot config reload via /admin/reload when files change. Polling-based (no inotify dependency). |
:::note The docker-compose.yml overrides SEMANTIC_CACHE_ENABLED to true and QDRANT_URL to http://qdrant:6333 (HTTP port, not gRPC). The code default uses port 6334 (gRPC), but the compose environment takes precedence. :::
Agent Gateway (L3)
Source: layers/agent-gateway/src/config.rs AgentGatewayConfig::from_env().
| Variable | Default | Required | Description |
|---|---|---|---|
PORT | 5000 | No | HTTP listen port (mapped to external 5001) |
REDIS_URL | redis://gw-redis:6379 | No | Redis connection URL for session state |
CLICKHOUSE_URL | http://clickhouse:8123 | No | ClickHouse HTTP URL for audit logging |
AI_GATEWAY_URL | http://ai-gateway:4000 | No | AI Gateway URL for LLM calls from agents |
OTEL_EXPORTER_OTLP_ENDPOINT | http://otel-collector:4317 | No | OpenTelemetry Collector gRPC endpoint |
OTEL_SERVICE_NAME | agent-gateway | No | Service name for OTel traces and metrics |
OTEL_RESOURCE_ATTRIBUTES | service.name=agent-gateway | No | OTel resource attributes |
SESSION_TTL_SECS | 3600 | No | Default agent session TTL in seconds |
MAX_CONCURRENT_TOOLS | 10 | No | Maximum concurrent tool executions per session |
HITL_WEBHOOK_URL | (empty) | No | Webhook URL for human-in-the-loop approval notifications |
ZITADEL_JWKS_URL | http://gw-zitadel:8080/oauth/v2/keys | No | Zitadel JWKS endpoint for JWT signature verification. Used for offline RS256 validation (no introspection). Cache refreshes every 30 minutes. |
ZITADEL_URL | http://gw-zitadel:8080 | No | Zitadel base URL for token introspection (fallback when JWKS unavailable) |
ZITADEL_CLIENT_ID | apisix-client | No | Zitadel client ID for token introspection |
ZITADEL_CLIENT_SECRET | apisix-client-secret | No | Zitadel client secret for token introspection |
RUST_LOG | agent_gateway=info | No | Rust log level filter |
RUST_TLS_CERT | (empty) | No | Path to TLS certificate file; when set, enables HTTPS instead of HTTP |
RUST_TLS_KEY | (empty) | No | Path to TLS private key file; required when RUST_TLS_CERT is set |
RUST_TLS_CA | (empty) | No | Path to CA certificate for client verification; enables mTLS when set |
MCP_HEALTH_CHECK_INTERVAL_SECS | 30 | No | Interval between MCP server health checks in seconds. Set to 0 to disable health checks. |
MCP_EXCLUDE_UNHEALTHY | false | No | When true, unhealthy MCP servers are excluded from tool discovery. Prevents routing tool calls to degraded servers. |
MCP_OAUTH_ENABLED | false | No | Enable MCP OAuth per RFC 9728 + RFC 8414. When enabled, the gateway acts as an OAuth proxy for MCP clients. |
MCP_OAUTH_ISSUER | (empty) | No | OAuth issuer URL (typically Zitadel organization URL). Used in .well-known/oauth-authorization-server response. |
MCP_OAUTH_JWKS_URL | (empty) | No | JWKS endpoint for MCP token validation. Proxied via /v1/mcp/auth/jwks. |
MCP_OAUTH_MODE | permissive | No | Token validation mode: strict (require token), optional (validate if present), permissive (skip validation). |
MCP_OAUTH_RESOURCE_URL | (empty) | No | Protected resource URL for RFC 9728 metadata. |
MCP_OAUTH_SCOPES | (empty) | No | Comma-separated OAuth scopes required for MCP access. |
CONFIG_WATCH_PATHS | (empty) | No | Comma-separated file paths to watch for config changes. Triggers hot reload via /admin/reload. |
Control Plane API
Source: layers/control-plane-api/src/clients.rs, main.rs, middleware.rs.
| Variable | Default | Required | Description |
|---|---|---|---|
REDIS_URL | redis://127.0.0.1:6379 | No | Redis connection URL |
APISIX_ADMIN_URL | http://localhost:9180 | No | APISIX Admin API base URL |
APISIX_ADMIN_KEY | edd1c9f034335f136f87ad84b625c8f1 | No | APISIX Admin API key (warning logged if using default) |
CLICKHOUSE_URL | http://localhost:8123 | No | ClickHouse HTTP URL for analytics queries |
AGENT_GATEWAY_URL | http://localhost:5001 | No | Agent Gateway URL for agent management |
ALLOWED_ORIGINS | http://localhost:3003,http://localhost:3004 | No | Comma-separated CORS allowed origins |
MASTER_KEY | sk-local-dev-key | No | Master API key for service-to-service auth |
ZITADEL_JWKS_URL | http://gw-zitadel:8080/oauth/v2/keys | No | Zitadel JWKS endpoint for JWT signature verification. Used for offline RS256 validation (no introspection). Cache refreshes every 30 minutes. |
ZITADEL_URL | http://localhost:8085 | No | Zitadel base URL for JWT introspection (fallback when JWKS unavailable) |
ZITADEL_CLIENT_ID | apisix-client | No | Zitadel client ID for JWT introspection |
ZITADEL_CLIENT_SECRET | apisix-client-secret | No | Zitadel client secret for JWT introspection |
RUST_LOG | control_plane_api=info | No | Rust log level filter |
ENVIRONMENT | (none) | No | Controls API behavior mode; set to development to allow manual API key entry in dev environments |
GATEZ_LICENSE_KEY | (none) | No | License key JWT. Without it, the platform runs in Community tier. Generate with scripts/generate-license.sh. |
RUST_TLS_CERT | (empty) | No | Path to TLS certificate file; when set, enables HTTPS instead of HTTP |
RUST_TLS_KEY | (empty) | No | Path to TLS private key file; required when RUST_TLS_CERT is set |
RUST_TLS_CA | (empty) | No | Path to CA certificate for client verification; enables mTLS when set |
VAULT_TOKEN | (empty) | No | HashiCorp Vault token for secret resolution. Used when provider key source is vault. |
VAULT_CACHE_TTL_SECS | 300 | No | Cache TTL for Vault secret lookups in seconds (default 5 min). Reduces Vault API calls. |
:::note In docker-compose.yml, the Control Plane API uses Docker-internal hostnames (e.g., http://apisix:9180, http://gw-zitadel:8080). The code defaults use localhost with external ports for local development without Docker. :::
Jaeger
| Variable | Default | Required | Description |
|---|---|---|---|
COLLECTOR_OTLP_ENABLED | true | No | Enable OTLP trace ingestion |
External ports: 16686 (UI), 14268 (HTTP collector).
OpenTelemetry Collector
Configured via infra/otel/config.yaml mounted into the container. No environment variables are set in docker-compose.yml.
External ports: 4317 (OTLP gRPC), 4318 (OTLP HTTP), 8889 (Prometheus metrics).
Prometheus
Configured via infra/prometheus/prometheus.yml. CLI flags: --storage.tsdb.retention.time=15d.
External port: 9090.
Grafana
| Variable | Default | Required | Description |
|---|---|---|---|
GF_SECURITY_ADMIN_USER | admin | No | Grafana admin username |
GF_SECURITY_ADMIN_PASSWORD | admin | No | Grafana admin password. Can be overridden via environment variable for production deployments. |
GF_INSTALL_PLUGINS | grafana-clickhouse-datasource | No | Plugins to install on startup |
External port: 3002 (mapped from internal 3000).
WARNING
Change GF_SECURITY_ADMIN_PASSWORD from the default admin value before deploying to production. Set it via environment variable in your deployment environment.
Mock Backend
No environment variables. Uses the httpbin image for testing.
External port: 8000 (mapped from internal 80).
Landing Page
No environment variables. Static nginx serving landing-page/ directory.
External port: 8899 (mapped from internal 80).