> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt > Use this file to discover all available pages before exploring further. # Server Configuration Reference > Complete reference for Temporal Server configuration options Temporal Server configuration is defined in YAML files that control all aspects of server behavior, from persistence to networking to security. ## Configuration File The server configuration can be loaded in multiple ways: 1. **Config directory** (legacy): Multiple YAML files in a directory structure 2. **Single config file**: Using `--config-file` flag or `TEMPORAL_SERVER_CONFIG_FILE_PATH` environment variable 3. **Embedded config**: Default configuration embedded in the binary ```bash theme={null} # Using config file temporal-server start --config-file config/development.yaml # Using environment variable export TEMPORAL_SERVER_CONFIG_FILE_PATH=/etc/temporal/config.yaml temporal-server start ``` ## Configuration Structure ### Top-Level Configuration | Field | Type | Description | | --------------------- | --------------------- | --------------------------------------------------------------- | | `global` | Global | Process-wide service configuration | | `persistence` | Persistence | Datastore configuration | | `log` | Log | Logging configuration | | `clusterMetadata` | ClusterMetadata | Cluster metadata and multi-cluster setup | | `dcRedirectionPolicy` | DCRedirectionPolicy | Datacenter redirection policy | | `services` | map\[string]Service | Per-service configuration (frontend, history, matching, worker) | | `archival` | Archival | Archival configuration | | `publicClient` | PublicClient | Internal service to frontend client configuration | | `dynamicConfigClient` | FileBasedClientConfig | Dynamic configuration client setup | | `namespaceDefaults` | NamespaceDefaults | Default settings for new namespaces | | `otel` | ExportConfig | OpenTelemetry exporter configuration | | `visibility` | Visibility | Visibility store configuration | ## Global Configuration ### Membership Cluster membership and gossip protocol configuration. ```yaml theme={null} global: membership: maxJoinDuration: 10s broadcastAddress: "" ``` | Field | Type | Default | Description | | ------------------ | -------- | ------- | ------------------------------------------------------- | | `maxJoinDuration` | duration | 10s | Maximum time to wait to join the gossip ring | | `broadcastAddress` | string | "" | Address communicated to other nodes (for NAT traversal) | ### PProf Go profiling endpoint configuration. ```yaml theme={null} global: pprof: port: 7936 host: localhost ``` | Field | Type | Default | Description | | ------ | ------ | --------- | ------------------------------------------- | | `port` | int | 0 | Port for pprof HTTP endpoint (0 = disabled) | | `host` | string | localhost | Host to bind pprof endpoint | ### TLS Configuration TLS settings for inter-service and client communication. ```yaml theme={null} global: tls: internode: server: certFile: /path/to/cert.pem keyFile: /path/to/key.pem requireClientAuth: true clientCaFiles: - /path/to/ca.pem client: serverName: temporal-server rootCaFiles: - /path/to/ca.pem frontend: server: certFile: /path/to/frontend-cert.pem keyFile: /path/to/frontend-key.pem systemWorker: certFile: /path/to/worker-cert.pem keyFile: /path/to/worker-key.pem client: serverName: temporal-frontend rootCaFiles: - /path/to/ca.pem ``` #### Server TLS | Field | Type | Description | | ------------------- | --------- | ---------------------------------------------------- | | `certFile` | string | Path to PEM-encoded certificate | | `keyFile` | string | Path to PEM-encoded private key | | `certData` | string | Base64-encoded certificate (alternative to certFile) | | `keyData` | string | Base64-encoded private key (alternative to keyFile) | | `clientCaFiles` | \[]string | CA certificates for client authentication | | `clientCaData` | \[]string | Base64-encoded CA certificates | | `requireClientAuth` | bool | Whether to require mutual TLS | #### Client TLS | Field | Type | Description | | ------------------------- | --------- | ------------------------------------- | | `serverName` | string | Expected server name for verification | | `rootCaFiles` | \[]string | Trusted CA certificates | | `rootCaData` | \[]string | Base64-encoded CA certificates | | `disableHostVerification` | bool | Skip hostname verification (insecure) | | `forceTLS` | bool | Use TLS even without certificates | ### Metrics Metrics configuration for Prometheus, StatsD, or M3. ```yaml theme={null} global: metrics: prometheus: listenAddress: "0.0.0.0:8000" handlerPath: "/metrics" ``` | Field | Type | Description | | ------------ | ------------------ | -------------------------------- | | `prometheus` | PrometheusConfig | Prometheus metrics configuration | | `statsd` | StatsdConfig | StatsD metrics configuration | | `m3` | M3Config | M3 metrics configuration | | `tags` | map\[string]string | Global tags for all metrics | ### Authorization Authentication and authorization configuration. ```yaml theme={null} global: authorization: jwtKeyProvider: keySourceURIs: - "https://auth.example.com/.well-known/jwks.json" refreshInterval: 1h permissionsClaimName: "permissions" authorizer: "default" claimMapper: "default" audience: "temporal" ``` | Field | Type | Description | | ---------------------- | -------------- | ----------------------------------------------------- | | `jwtKeyProvider` | JWTKeyProvider | JWT signing key configuration | | `permissionsClaimName` | string | JWT claim containing permissions | | `permissionsRegex` | string | Regex to parse permissions claim | | `authorizer` | string | Authorizer implementation ("" or "default") | | `claimMapper` | string | Claim mapper implementation | | `authHeaderName` | string | HTTP header for auth token (default: "authorization") | | `authExtraHeaderName` | string | Additional auth header | | `audience` | string | Expected JWT audience | ## Persistence Configuration Database and datastore configuration. ```yaml theme={null} persistence: defaultStore: default visibilityStore: visibility numHistoryShards: 4 datastores: default: sql: pluginName: postgres databaseName: temporal connectAddr: localhost:5432 connectProtocol: tcp user: temporal password: temporal maxConns: 20 maxIdleConns: 20 maxConnLifetime: 1h visibility: sql: pluginName: postgres databaseName: temporal_visibility connectAddr: localhost:5432 connectProtocol: tcp user: temporal password: temporal maxConns: 10 maxIdleConns: 10 ``` ### Persistence Fields | Field | Type | Description | | -------------------------- | --------------------- | --------------------------------------------- | | `defaultStore` | string | Name of default datastore for temporal data | | `visibilityStore` | string | Name of datastore for visibility records | | `secondaryVisibilityStore` | string | Secondary visibility store for dual writes | | `numHistoryShards` | int32 | Number of history shards (must be power of 2) | | `datastores` | map\[string]DataStore | Named datastore configurations | ### SQL Datastore | Field | Type | Description | | -------------------- | ------------------ | ----------------------------------------- | | `pluginName` | string | SQL plugin: "postgres", "mysql", "sqlite" | | `databaseName` | string | Database name | | `connectAddr` | string | Database host:port | | `connectProtocol` | string | Connection protocol: "tcp", "unix" | | `user` | string | Database user | | `password` | string | Database password | | `connectAttributes` | map\[string]string | Additional connection parameters | | `maxConns` | int | Maximum connections | | `maxIdleConns` | int | Maximum idle connections | | `maxConnLifetime` | duration | Maximum connection lifetime | | `taskScanPartitions` | int | Partitions for task scanning (Vitess) | ### Cassandra Datastore ```yaml theme={null} datastores: default: cassandra: hosts: "127.0.0.1" port: 9042 keyspace: temporal user: cassandra password: cassandra datacenter: datacenter1 maxConns: 20 connectTimeout: 600ms timeout: 10s ``` | Field | Type | Description | | ---------------- | -------------------- | ------------------------------- | | `hosts` | string | Comma-separated Cassandra hosts | | `port` | int | Cassandra port | | `keyspace` | string | Keyspace name | | `user` | string | Username | | `password` | string | Password | | `datacenter` | string | Local datacenter | | `maxConns` | int | Maximum connections per host | | `connectTimeout` | duration | Connection timeout | | `timeout` | duration | Query timeout | | `writeTimeout` | duration | Write timeout | | `consistency` | CassandraConsistency | Consistency settings | ### Elasticsearch Datastore ```yaml theme={null} datastores: visibility: elasticsearch: url: "https://localhost:9200" indices: visibility: temporal-visibility-dev username: elastic password: changeme ``` ## Service Configuration Per-service settings for frontend, history, matching, and worker services. ```yaml theme={null} services: frontend: rpc: grpcPort: 7233 httpPort: 7243 membershipPort: 6933 bindOnIP: "0.0.0.0" history: rpc: grpcPort: 7234 membershipPort: 6934 bindOnIP: "0.0.0.0" matching: rpc: grpcPort: 7235 membershipPort: 6935 bindOnIP: "0.0.0.0" worker: rpc: grpcPort: 7239 membershipPort: 6939 bindOnIP: "0.0.0.0" ``` ### RPC Configuration | Field | Type | Description | | -------------------------------- | ---------------------- | ----------------------------------------------- | | `grpcPort` | int | Port for gRPC service | | `httpPort` | int | Port for HTTP/gRPC-Web (frontend only) | | `membershipPort` | int | Port for cluster membership | | `bindOnLocalHost` | bool | Bind to localhost only | | `bindOnIP` | string | Specific IP to bind (overrides bindOnLocalHost) | | `httpAdditionalForwardedHeaders` | \[]string | Additional headers to forward from HTTP to gRPC | | `keepAliveServerConfig` | KeepAliveConfig | gRPC keepalive configuration | | `clientConnectionConfig` | ClientConnectionConfig | Client connection settings | ## Dynamic Configuration Dynamic configuration allows runtime configuration changes without server restart. ```yaml theme={null} dynamicConfigClient: filepath: config/dynamicconfig/development.yaml pollInterval: 10s ``` | Field | Type | Description | | -------------- | -------- | ------------------------------------- | | `filepath` | string | Path to dynamic config YAML file | | `pollInterval` | duration | How often to check for config changes | ## Archival Configuration History and visibility archival to long-term storage. ```yaml theme={null} archival: history: state: "enabled" enableRead: true provider: filestore: fileMode: "0666" dirMode: "0766" s3store: region: "us-east-1" visibility: state: "enabled" enableRead: true provider: filestore: fileMode: "0666" dirMode: "0766" ``` ### Archival States * `enabled`: Archival is enabled * `disabled`: Archival is disabled * `paused`: Archival is paused temporarily ### Archival Providers * **filestore**: Local or network filesystem * **s3store**: Amazon S3 or S3-compatible storage * **gstorage**: Google Cloud Storage ## Cluster Metadata Multi-cluster configuration. ```yaml theme={null} clusterMetadata: enableGlobalNamespace: true failoverVersionIncrement: 10 masterClusterName: "primary" currentClusterName: "primary" clusterInformation: primary: enabled: true initialFailoverVersion: 1 rpcAddress: "localhost:7233" secondary: enabled: true initialFailoverVersion: 2 rpcAddress: "remote-host:7233" ``` | Field | Type | Description | | -------------------------- | ----------------------- | ------------------------------ | | `enableGlobalNamespace` | bool | Enable global namespaces | | `failoverVersionIncrement` | int | Version increment for failover | | `masterClusterName` | string | Name of the master cluster | | `currentClusterName` | string | Name of this cluster | | `clusterInformation` | map\[string]ClusterInfo | Cluster details | ## Namespace Defaults Default settings applied to new namespaces. ```yaml theme={null} namespaceDefaults: archival: history: state: "disabled" URI: "file:///tmp/temporal-archival/history" visibility: state: "disabled" URI: "file:///tmp/temporal-archival/visibility" ``` ## See Also * [Dynamic Config Reference](/reference/dynamic-config) * [Environment Variables](/reference/environment-variables) * [Database Schema Reference](/reference/database-schema) * [CLI Commands](/reference/cli/start)