Environment Variables Reference

Temporal Server can be configured using environment variables. These variables override default values and provide an alternative to configuration files for containerized deployments.

Configuration File Selection

TEMPORAL_SERVER_CONFIG_FILE_PATH

Specifies the path to the server configuration file.

Type: String (file path)
Default: Not set (uses config directory or embedded config)
Example: /etc/temporal/config.yaml

export TEMPORAL_SERVER_CONFIG_FILE_PATH=/etc/temporal/config.yaml
temporal-server start

TEMPORAL_ROOT

Root directory for Temporal Server execution (deprecated).

Type: String (directory path)
Default: . (current directory)
Deprecated: Use --config-file instead

TEMPORAL_CONFIG_DIR

Directory containing configuration files (deprecated).

Type: String (directory path)
Default: config
Deprecated: Use --config-file instead

export TEMPORAL_CONFIG_DIR=/etc/temporal/config

TEMPORAL_ENVIRONMENT

Environment name for configuration selection (deprecated).

Type: String
Default: development
Values: development, production, etc.
Deprecated: Use --config-file instead

TEMPORAL_AVAILABILITY_ZONE

Availability zone for the server instance (deprecated).

Type: String
Default: Not set
Deprecated: Use --config-file instead

TEMPORAL_AVAILABILTY_ZONE

Legacy typo version of availability zone variable (deprecated).

Type: String
Default: Not set
Deprecated: Use TEMPORAL_AVAILABILITY_ZONE or --config-file

Authorization

TEMPORAL_ALLOW_NO_AUTH

Allows server to start without an authorizer configured.

Type: Boolean
Default: false
Values: true, false, 1, 0

export TEMPORAL_ALLOW_NO_AUTH=true
temporal-server start

Warning: Only use in development. Production deployments should use proper authorization.

Service Selection

TEMPORAL_SERVICES

Comma-separated list of services to start.

Type: String (comma-separated)
Default: frontend,history,matching,worker
Values: Any combination of frontend, history, matching, worker, internal-frontend

# Start only frontend and history services
export TEMPORAL_SERVICES=frontend,history
temporal-server start

# Or use command-line flag
temporal-server start --service frontend --service history

Database Configuration

While database configuration is typically in config files, some connection strings can use environment variables.

Connection String Variables

You can use environment variable substitution in config files:

persistence:
  datastores:
    default:
      sql:
        pluginName: postgres
        connectAddr: "${DB_HOST}:${DB_PORT}"
        databaseName: "${DB_NAME}"
        user: "${DB_USER}"
        password: "${DB_PASSWORD}"

Common database variables:

DB_HOST: Database host
DB_PORT: Database port
DB_NAME: Database name
DB_USER: Database username
DB_PASSWORD: Database password

TLS Configuration

TLS certificates can reference environment variables:

global:
  tls:
    frontend:
      server:
        certFile: "${TLS_CERT_FILE}"
        keyFile: "${TLS_KEY_FILE}"

Common TLS variables:

TLS_CERT_FILE: Path to TLS certificate
TLS_KEY_FILE: Path to TLS private key
TLS_CA_FILE: Path to CA certificate

Logging

LOG_LEVEL

Sets the logging level.

Type: String
Default: info
Values: debug, info, warn, error, fatal

log:
  level: "${LOG_LEVEL}"

LOG_FORMAT

Sets the log output format.

Type: String
Default: json
Values: json, console

Metrics

PROMETHEUS_ENDPOINT

Prometheus metrics endpoint address.

Type: String (host:port)
Default: Not set

global:
  metrics:
    prometheus:
      listenAddress: "${PROMETHEUS_ENDPOINT}"

STATSD_ENDPOINT

StatsD metrics endpoint.

Type: String (host:port)
Default: Not set

OpenTelemetry

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP exporter endpoint for traces and metrics.

Type: String (URL)
Default: Not set
Example: http://localhost:4318

OTEL_RESOURCE_ATTRIBUTES

Resource attributes for OTEL spans.

Type: String (key=value pairs)
Default: Not set
Example: service.name=temporal-server,environment=production

Dynamic Configuration

DYNAMIC_CONFIG_FILE_PATH

Path to dynamic configuration file.

Type: String (file path)
Default: Not set

dynamicConfigClient:
  filepath: "${DYNAMIC_CONFIG_FILE_PATH}"

Advanced Configuration

NUM_HISTORY_SHARDS

Number of history shards (must be power of 2).

Type: Integer
Default: 4
Values: Powers of 2 (4, 8, 16, 32, etc.)

persistence:
  numHistoryShards: ${NUM_HISTORY_SHARDS}

Important: Cannot be changed after initial setup.

BIND_ON_IP

IP address to bind all services.

Type: String (IP address)
Default: Not set (binds to localhost)
Values: Valid IP addresses or 0.0.0.0 for all interfaces

services:
  frontend:
    rpc:
      bindOnIP: "${BIND_ON_IP}"

FRONTEND_GRPC_PORT

Frontend gRPC port.

Type: Integer
Default: 7233

FRONTEND_HTTP_PORT

Frontend HTTP port.

Type: Integer
Default: 7243

HISTORY_GRPC_PORT

History service gRPC port.

Type: Integer
Default: 7234

MATCHING_GRPC_PORT

Matching service gRPC port.

Type: Integer
Default: 7235

WORKER_GRPC_PORT

Worker service gRPC port.

Type: Integer
Default: 7239

Kubernetes/Docker Examples

Docker Compose

version: '3.8'
services:
  temporal:
    image: temporalio/auto-setup:latest
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=temporal
      - DB_USER=temporal
      - DB_PASSWORD=temporal
      - DYNAMIC_CONFIG_FILE_PATH=/etc/temporal/config/dynamicconfig.yaml
      - PROMETHEUS_ENDPOINT=0.0.0.0:8000
      - LOG_LEVEL=info
      - NUM_HISTORY_SHARDS=4
      - BIND_ON_IP=0.0.0.0
    ports:
      - "7233:7233"
      - "7243:7243"
      - "8000:8000"

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: temporal-env
data:
  DB_HOST: postgres-service
  DB_PORT: "5432"
  DB_NAME: temporal
  LOG_LEVEL: info
  PROMETHEUS_ENDPOINT: "0.0.0.0:8000"
---
apiVersion: v1
kind: Secret
metadata:
  name: temporal-db-secret
type: Opaque
stringData:
  DB_USER: temporal
  DB_PASSWORD: changeme
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: temporal
spec:
  selector:
    matchLabels:
      app: temporal
  template:
    metadata:
      labels:
        app: temporal
    spec:
      containers:
      - name: temporal
        image: temporalio/auto-setup:latest
        envFrom:
        - configMapRef:
            name: temporal-env
        - secretRef:
            name: temporal-db-secret
        ports:
        - containerPort: 7233
        - containerPort: 7243

Environment Variable Precedence

Configuration is resolved in this order (highest to lowest priority):

Command-line flags
Environment variables
Configuration file values
Default values

Example:

# Config file has: grpcPort: 7233
# Environment has: FRONTEND_GRPC_PORT=8233
# Command line has: --grpcPort 9233
# Result: Uses 9233 (command-line flag wins)

Security Best Practices

Never commit secrets: Don’t put passwords or keys in version control
Use secret management: Use Kubernetes Secrets, AWS Secrets Manager, or HashiCorp Vault
Least privilege: Grant minimal permissions to database users
Rotate credentials: Regularly rotate passwords and certificates
Audit logging: Enable audit logs for security-sensitive operations

Troubleshooting

Variable Not Taking Effect

Check variable name spelling (case-sensitive)
Verify environment is set before starting server
Check for command-line flag overrides
Review server logs for configuration errors

Connection Issues

Verify database environment variables are set correctly
Test database connectivity manually
Check network policies and firewall rules
Verify credentials are valid

TLS Errors

Verify certificate paths are correct
Check certificate validity (not expired)
Ensure CA certificates are available
Verify hostname matches certificate CN/SAN

Configuration

CLI Commands

​Configuration File Selection

​TEMPORAL_SERVER_CONFIG_FILE_PATH

​TEMPORAL_ROOT

​TEMPORAL_CONFIG_DIR

​TEMPORAL_ENVIRONMENT

​TEMPORAL_AVAILABILITY_ZONE

​TEMPORAL_AVAILABILTY_ZONE

​Authorization

​TEMPORAL_ALLOW_NO_AUTH

​Service Selection

​TEMPORAL_SERVICES

​Database Configuration

​Connection String Variables

​TLS Configuration

​Logging

​LOG_LEVEL

​LOG_FORMAT

​Metrics

​PROMETHEUS_ENDPOINT

​STATSD_ENDPOINT

​OpenTelemetry

​OTEL_EXPORTER_OTLP_ENDPOINT

​OTEL_RESOURCE_ATTRIBUTES

​Dynamic Configuration

​DYNAMIC_CONFIG_FILE_PATH

​Advanced Configuration

​NUM_HISTORY_SHARDS

​BIND_ON_IP

​FRONTEND_GRPC_PORT

​FRONTEND_HTTP_PORT

​HISTORY_GRPC_PORT

​MATCHING_GRPC_PORT

​WORKER_GRPC_PORT

​Kubernetes/Docker Examples

​Docker Compose

​Kubernetes ConfigMap

​Environment Variable Precedence

​Security Best Practices

​Troubleshooting

​Variable Not Taking Effect

​Connection Issues

​TLS Errors

​See Also

Build docs developers (and LLMs) love