Deployment

This page covers how the server is packaged, configured, and operated. It is server-engineer-oriented; the user-facing operations docs at docs.temporal.io cover production deployment from the operator's perspective.

Packaging

Artifact	Source
temporal-server binary	cmd/server/
temporal-cassandra-tool	cmd/tools/cassandra/
temporal-sql-tool	cmd/tools/sql/
Docker image	docker/targets/server.Dockerfile and make docker-buildx-* Make targets
Helm charts	Lives in a separate temporalio/helm-charts repo; not in this tree.

make builds all binaries; make docker-buildx-temporal-server cross-builds the Docker image.

Configuration

A complete server config is loaded from YAML via common/config/. Examples are kept in config/. The simplest working config is config/development-sqlite.yaml (the default symlink target of config/development.yaml).

The CLI accepts:

temporal-server start                              # uses embedded default config
temporal-server --config-file /etc/temporal/cluster.yaml start
temporal-server --env development-postgres12 --allow-no-auth start

The fields are documented in common/config/config.go; a non-exhaustive map appears on Reference → configuration.

Services to run

A "Temporal cluster" is a fleet of temporal-server processes. Each process can run any subset of the services declared in temporal/server.go:

DefaultServices = []string{
    "frontend",
    "history",
    "matching",
    "worker",
}

Production clusters typically run them as separate Kubernetes Deployments — Frontend and Worker scale independently of History and Matching, which scale by shard / partition count.

Persistence

Pick one of the supported backends:

• Cassandra — the original; preferred for high-throughput clusters. Setup with temporal-cassandra-tool setup-schema.
• MySQL / PostgreSQL — supported with the same SQL plugin. Setup with temporal-sql-tool.
• SQLite — embedded; great for development and small clusters.

Visibility can be the same backend or Elasticsearch via go.olivere/elastic/v7.

Schema migration is handled by the schema tools — every release ships with a versioned schema diff under schema/<backend>/<dbname>/versioned/. The migration tools idempotently apply unrun migrations.

Lifecycle

Process startup sequence (see Architecture for the diagram):

1. Parse CLI flags (cmd/server/main.go).
2. Load config + dynamic config (temporal/fx.go).
3. Construct authorizer + claim mapper.
4. Build fx graph; start all services in dependency order.
5. Each service joins the membership ring (common/membership/).
6. History acquires shards; Matching loads task-queue partitions on demand.
7. Frontend accepts traffic.

Graceful shutdown reverses the order: drain in-flight RPCs, persist queue ack levels, leave the ring.

Multi-cluster deployment

Running more than one cluster requires:

• Each cluster has a unique clusterName in config.
• A common cluster_metadata row registering each cluster's address.
• The EnableGlobalNamespace dynamic-config flag.
• Replication enabled on each shared namespace.

See Replication for the source-level walkthrough.

Operator tooling

• tdbg (cmd/tools/tdbg/) — diagnostic CLI. Read shards, list pending tasks, inspect DLQs, refresh cache entries.
• temporal CLI — separate repo (temporalio/cli) — operator and SDK-facing.
• Web UI — separate repo (temporalio/ui) — operator-facing dashboard.

Production hardening

Notable knobs operators usually configure:

• TLS — enable on every gRPC listener via tls: blocks in YAML; certificate rotation lives in common/rpc/encryption/.
• Authorization — provide a claimMapper and authorizer JAR via the JWT block in YAML or a custom plugin.
• Rate limits — dynamic-config keys under frontend.*RPS and history.*RPS.
• Visibility — choose between primary-DB visibility, dedicated SQL visibility, or Elasticsearch.
• Archival — set historyArchival and visibilityArchival per namespace; configure the provider in YAML.

Where to read more

• Reference → configuration
• Reference → dependencies
• How to monitor
• Security