Skip to main content
Temporal Server is a durable execution platform that can be deployed in various configurations to meet different operational requirements. This guide covers the available deployment options and architecture considerations.

​
Deployment Options

Temporal Server supports multiple deployment strategies:

Docker

Run Temporal Server using Docker containers for development and production

Kubernetes

Deploy to Kubernetes using Helm charts for scalable production workloads

Binary Deployment

Run the compiled binary directly on bare metal or virtual machines

Temporal Cloud

Fully managed service with zero operational overhead

​
Architecture Components

A Temporal Server deployment consists of several key services:

​
Core Services

Frontend Service
  • Handles all incoming API requests from clients
  • Default ports: gRPC 7233, HTTP 7243
  • Stateless and horizontally scalable
History Service
  • Maintains workflow execution state and history
  • Default ports: gRPC 7234, membership 6934
  • Stateful service using consistent hashing for sharding
Matching Service
  • Routes workflow and activity tasks to workers
  • Default ports: gRPC 7235, membership 6935
  • Manages task queues and load balancing
Worker Service
  • Executes internal system workflows
  • Default ports: gRPC 7239, membership 6939
  • Required for archival and other background operations
Internal Frontend Service (Optional)
  • Separate internal-only API endpoint
  • Default ports: gRPC 7236, HTTP 7246
  • Used for internal cross-cluster communication

​
Storage Requirements

Temporal requires two types of data stores:
Stores workflow execution state, history events, and system metadata.Supported Databases:
  • Cassandra 3.11+
  • MySQL 8.0+
  • PostgreSQL 12+ (postgres12, postgres12_pgx)
  • SQLite (development only)
Key Tables:
  • namespaces - Namespace metadata
  • executions - Workflow execution state
  • shards - Shard ownership and range IDs
  • tasks - Transfer, timer, and replication tasks
Enables workflow search and listing operations.Supported Databases:
  • MySQL 8.0+ (standard visibility)
  • PostgreSQL 12+ (standard visibility)
  • Elasticsearch 7.10+ (advanced visibility)
Features:
  • Standard: Basic filtering and search
  • Advanced: Full-text search, custom search attributes

​
Deployment Considerations

​
Resource Requirements

Minimal Setup:
CPU: 2 cores
Memory: 4 GB RAM
Database: SQLite or single MySQL/PostgreSQL instance
History Shards: 4
Suitable for:
  • Local development
  • Testing
  • CI/CD environments

​
High Availability

For production deployments, ensure:
  • Multiple Service Instances: Run at least 2 instances of each service
  • Database Replication: Use replicated database clusters
  • Load Balancing: Distribute traffic across Frontend instances
  • Persistent Storage: Use durable storage for archival if enabled
  • Monitoring: Deploy Prometheus and Grafana for metrics

​
Network Configuration

All services use membership ports for internal cluster coordination via the ringpop protocol.
Service Communication:
  - Frontend ↔ History/Matching/Worker (internal gRPC)
  - Clients → Frontend (external gRPC/HTTP)
  - Services ↔ Database (TCP)
  - Services ↔ Elasticsearch (HTTP, optional)

​
Security Considerations

​
TLS Configuration

Temporal supports mutual TLS (mTLS) for:
  • Internode Communication: Between Temporal services
  • Frontend Communication: Between clients and Frontend
See the Configuration Guide for TLS setup details.

​
Authentication & Authorization

Configure JWT-based authentication:
  • Key source URIs for public keys
  • Claims mapping for permissions
  • Custom authorizer and claim mapper plugins

​
Network Security

  • Use private networks for service-to-service communication
  • Expose only Frontend service to clients
  • Implement network policies in Kubernetes
  • Use database connection encryption (TLS)

​
Monitoring and Observability

​
Metrics

Temporal emits metrics in Prometheus format: 
global:
  metrics:
    prometheus:
      framework: "opentelemetry"  # or "tally"
      timerType: "histogram"
      listenAddress: "127.0.0.1:8000"
Alternatively, use StatsD: 
global:
  metrics:
    statsd:
      hostPort: "127.0.0.1:8125"
      prefix: "temporal"

​
Profiling

Enable pprof for runtime profiling: 
global:
  pprof:
    port: 7936  # Set to 0 to disable

​
Logging

Configure log output: 
log:
  stdout: true
  level: info  # debug, info, warn, error

​
Scaling Guidelines

​
Horizontal Scaling

Frontend & Matching: Scale based on request rate
  • Add instances when CPU > 70%
  • Each instance handles ~10k requests/sec
History: Scale based on workflow execution rate
  • Shards are distributed across History instances
  • More shards = better distribution
  • Each instance can handle ~1k-2k workflows/sec

​
Vertical Scaling

Increase resources when:
  • History Service: Large workflow histories (>10k events)
  • Matching Service: High task queue throughput
  • Frontend: Complex query patterns

​
Database Scaling

Connection Pool Configuration:
  maxConns: 20          # Maximum connections
  maxIdleConns: 20      # Idle connections to maintain
  maxConnLifetime: 1h   # Connection lifetime
Adjust based on:
  • Number of service instances
  • Database capacity
  • Query latency

​
Next Steps

1

Choose Deployment Method

Select Docker, Kubernetes, or binary deployment based on your infrastructure
2

Setup Database

Configure your persistence and visibility stores
3

Configure Server

Create server configuration file
4

Deploy Services

Start Temporal services and verify connectivity
5

Setup Monitoring

Configure Prometheus and Grafana for observability

Production Checklist

  • Database replication configured
  • Multiple service instances deployed
  • TLS certificates generated and configured
  • Monitoring and alerting setup
  • Backup and disaster recovery plan
  • Load testing completed
  • Security review performed

Build docs developers (and LLMs) love

Get started for freeTalk to us