> ## 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.

# Deployment Overview

> Learn about deployment options and architecture for Temporal Server

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:

<CardGroup cols={2}>
  <Card title="Docker" icon="docker" href="/deployment/docker">
    Run Temporal Server using Docker containers for development and production
  </Card>

  <Card title="Kubernetes" icon="kubernetes">
    Deploy to Kubernetes using Helm charts for scalable production workloads
  </Card>

  <Card title="Binary Deployment" icon="server">
    Run the compiled binary directly on bare metal or virtual machines
  </Card>

  <Card title="Temporal Cloud" icon="cloud">
    Fully managed service with zero operational overhead
  </Card>
</CardGroup>

## 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:

<AccordionGroup>
  <Accordion title="Persistence Store" icon="database">
    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
  </Accordion>

  <Accordion title="Visibility Store" icon="eye">
    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
  </Accordion>
</AccordionGroup>

## Deployment Considerations

### Resource Requirements

<Tabs>
  <Tab title="Development">
    **Minimal Setup:**

    ```yaml theme={null}
    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
  </Tab>

  <Tab title="Production">
    **Recommended Setup:**

    ```yaml theme={null}
    Frontend: 2-3 instances (2 CPU, 4 GB RAM each)
    History: 3-5 instances (4 CPU, 8 GB RAM each)
    Matching: 2-3 instances (2 CPU, 4 GB RAM each)
    Worker: 1-2 instances (2 CPU, 4 GB RAM each)
    Database: HA cluster with replication
    History Shards: 512-4096 (based on throughput)
    ```

    Suitable for:

    * Production workloads
    * High availability
    * Horizontal scaling
  </Tab>
</Tabs>

### 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

<Note>
  All services use membership ports for internal cluster coordination via the ringpop protocol.
</Note>

```yaml theme={null}
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](/deployment/configuration) 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:

```yaml theme={null}
global:
  metrics:
    prometheus:
      framework: "opentelemetry"  # or "tally"
      timerType: "histogram"
      listenAddress: "127.0.0.1:8000"
```

Alternatively, use StatsD:

```yaml theme={null}
global:
  metrics:
    statsd:
      hostPort: "127.0.0.1:8125"
      prefix: "temporal"
```

### Profiling

Enable pprof for runtime profiling:

```yaml theme={null}
global:
  pprof:
    port: 7936  # Set to 0 to disable
```

### Logging

Configure log output:

```yaml theme={null}
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

```yaml theme={null}
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

<Steps>
  <Step title="Choose Deployment Method">
    Select Docker, Kubernetes, or binary deployment based on your infrastructure
  </Step>

  <Step title="Setup Database">
    [Configure your persistence and visibility stores](/deployment/database-setup)
  </Step>

  <Step title="Configure Server">
    [Create server configuration file](/deployment/configuration)
  </Step>

  <Step title="Deploy Services">
    Start Temporal services and verify connectivity
  </Step>

  <Step title="Setup Monitoring">
    Configure Prometheus and Grafana for observability
  </Step>
</Steps>

<Card title="Production Checklist" icon="check">
  * [ ] 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
</Card>