Installation

Complete installation guide for Temporal Server in different environments

Overview

Temporal Server can be installed and configured in multiple ways depending on your environment and requirements. This guide covers installation from pre-built binaries, building from source, and configuring various persistence backends.

Installation Methods

Temporal CLI (Recommended)

The easiest way to install and run Temporal Server for development.

macOS

brew install temporal

Linux

Download the latest release from the Temporal CLI releases page:

# Download for Linux (replace VERSION with the latest version)
curl -L https://github.com/temporalio/cli/releases/download/VERSION/temporal_cli_VERSION_linux_amd64.tar.gz | tar xz

# Move to system path
sudo mv temporal /usr/local/bin/

# Verify installation
temporal --version

Windows

Download the Windows binary from the releases page or use a package manager like Scoop.

Start the Server

temporal server start-dev

Build from Source

Build Temporal Server from source for development or customization.

Prerequisites

• Go 1.26.0 or later: Check your version with go version
• Git: For cloning the repository
• Make: For using build targets
• Protocol Buffers Compiler: Only if modifying .proto files
• Docker: Optional, for running dependencies

The minimum required Go version is specified in the go.mod file in the repository.

Build Steps

1. Clone the Repository

   git clone https://github.com/temporalio/temporal.git
   cd temporal
   
2. Build the Server

   For the first build, use the default make command to install dependencies and build all binaries:

   make
   

   For subsequent builds, you can build just the binaries:

   make bins
   

   This creates the following binaries:

   • temporal-server: Main server binary
   • temporal-cassandra-tool: Cassandra schema management tool
   • temporal-sql-tool: SQL database schema management tool
   • temporal-elasticsearch-tool: Elasticsearch index management tool
   • tdbg: Temporal debugger tool
3. Verify the Build

   ./temporal-server --version
   

Build for Specific Platforms

# Build for Linux
GOOS=linux GOARCH=amd64 make bins

# Build for macOS (ARM)
GOOS=darwin GOARCH=arm64 make bins

# Build for Windows
GOOS=windows GOARCH=amd64 make bins

Docker

Run Temporal Server using Docker containers.

Using Docker Compose

The repository includes Docker Compose files for running Temporal with all dependencies:

# Clone the repository
git clone https://github.com/temporalio/temporal.git
cd temporal

# Start all services and dependencies
make start-dependencies

This starts:

• MySQL 8.0
• PostgreSQL 13.5
• Cassandra 3.11
• Elasticsearch 7.10.1
• Prometheus (metrics)
• Grafana (visualization)
• Temporal Web UI

Stop Dependencies

make stop-dependencies

Persistence Configuration

Temporal Server supports multiple database backends for persistence. Choose based on your requirements:

SQLite (Development Only)

Best for local development and testing. Data can be in-memory or file-based.

In-Memory

# Using Temporal CLI
temporal server start-dev

# Using built binary
make start-sqlite
# Or directly:
./temporal-server --config-file config/development-sqlite.yaml --allow-no-auth start

In-memory SQLite does not persist data between server restarts. All workflows and history will be lost when the server stops.

File-Based

# Using make target
make start-sqlite-file

# Or with custom config
./temporal-server --config-file config/development-sqlite-file.yaml --allow-no-auth start

File-based SQLite persists data to disk, allowing you to restart the server without losing data.

MySQL

Recommended for production deployments with moderate scale.

1. Start MySQL

   # Using Docker
   docker run -d --name temporal-mysql \
     -e MYSQL_ROOT_PASSWORD=root \
     -p 3306:3306 \
     mysql:8.0.29-oracle
   
   # Or use the provided Docker Compose
   make start-dependencies
   
2. Install Schema

   make install-schema-mysql
   

   This command:

   • Creates the temporal and temporal_visibility databases
   • Installs the required schema for both databases
   • Applies all schema migrations

   You can customize database names using environment variables:

   TEMPORAL_DB=my_temporal VISIBILITY_DB=my_visibility make install-schema-mysql
   
3. Start the Server

   make start-mysql
   
   # Or directly:
   ./temporal-server --env development-mysql8 --allow-no-auth start
   

PostgreSQL

Recommended for production deployments, offers excellent performance and reliability.

1. Start PostgreSQL

   # Using Docker
   docker run -d --name temporal-postgresql \
     -e POSTGRES_USER=temporal \
     -e POSTGRES_PASSWORD=temporal \
     -p 5432:5432 \
     postgres:13.5
   
   # Or use Docker Compose
   make start-dependencies
   
2. Install Schema

   make install-schema-postgresql
   

   Default credentials:

   • User: temporal
   • Password: temporal

   To use custom credentials:

   SQL_USER=myuser SQL_PASSWORD=mypassword make install-schema-postgresql
   
3. Start the Server

   make start-postgresql
   
   # Or directly:
   ./temporal-server --env development-postgres12 --allow-no-auth start
   

Cassandra

Best for large-scale deployments requiring horizontal scalability.

1. Start Cassandra

   # Using Docker
   docker run -d --name temporal-cassandra \
     -e CASSANDRA_LISTEN_ADDRESS=127.0.0.1 \
     -p 9042:9042 \
     cassandra:3.11
   
   # Or use Docker Compose
   make start-dependencies
   
2. Install Schema

   With Elasticsearch for advanced visibility:

   make install-schema-cass-es
   

   Without Elasticsearch:

   ./temporal-cassandra-tool create -k temporal
   ./temporal-cassandra-tool -k temporal setup-schema -v 0.0
   ./temporal-cassandra-tool -k temporal update-schema -d ./schema/cassandra/temporal/versioned
   
3. Start the Server

   make start-cass-es
   
   # Or directly:
   ./temporal-server --env development-cass-es --allow-no-auth start
   

Server Configuration

Temporal Server can be configured using YAML configuration files or command-line flags.

Configuration File

Create a custom configuration file based on the provided templates in the config/ directory:

./temporal-server --config-file /path/to/config.yaml start

Configuration Options

Key configuration sections:

Persistence

persistence:
  defaultStore: sqlite-default
  visibilityStore: sqlite-visibility
  numHistoryShards: 1
  datastores:
    sqlite-default:
      sql:
        pluginName: "sqlite"
        databaseName: "default"
        connectAddr: "localhost"
        connectAttributes:
          mode: "memory"
          cache: "private"

services:
  frontend:
    rpc:
      grpcPort: 7233
      membershipPort: 6933
      bindOnLocalHost: true
      httpPort: 7243
  
  history:
    rpc:
      grpcPort: 7234
      membershipPort: 6934
      bindOnLocalHost: true
  
  matching:
    rpc:
      grpcPort: 7235
      membershipPort: 6935
      bindOnLocalHost: true
  
  worker:
    rpc:
      grpcPort: 7239
      membershipPort: 6939
      bindOnLocalHost: true

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

global:
  metrics:
    prometheus:
      framework: "tally"  # or "opentelemetry"
      timerType: "histogram"
      listenAddress: "127.0.0.1:8000"

Environment-Based Configuration

For legacy configuration style using environment variables:

./temporal-server \
  --env development \
  --config config \
  --zone us-east-1 \
  --allow-no-auth \
  start

Command-Line Flags

Common flags:

• --config-file: Path to configuration file
• --env: Runtime environment (deprecated, use —config-file)
• --allow-no-auth: Allow server to run without authorization
• --service: Specify which services to start (frontend, history, matching, worker)

Running Specific Services

You can run individual Temporal services instead of all services:

# Run only frontend and history services
./temporal-server --config-file config.yaml --service frontend --service history start

# Using environment variable
TEMPORAL_SERVICES=frontend,history ./temporal-server --config-file config.yaml start

Default services: frontend, history, matching, worker

Validation and Troubleshooting

Validate Configuration

# Render and validate configuration
./temporal-server --config-file config.yaml render-config

Validate Dynamic Configuration

./temporal-server validate-dynamic-config config/dynamicconfig/development-sql.yaml

Check Server Health

# List namespaces
temporal operator namespace list

# Check server version
./temporal-server --version

Common Issues

Database connection failed

Verify:

• Database service is running: docker ps or service status
• Credentials are correct in configuration file
• Network connectivity: telnet localhost 3306 (MySQL) or 5432 (PostgreSQL)
• Schema is installed: Run appropriate install-schema-* command

Port already in use

Check if another Temporal instance is running:

lsof -i :7233

Change ports in configuration file if needed.

Authorization errors

For development, use the --allow-no-auth flag:

./temporal-server --config-file config.yaml --allow-no-auth start

For production, configure proper authorization in the config file.

Schema version mismatch

Update the schema to the latest version:

# For MySQL
./temporal-sql-tool -u temporal --pw temporal --pl mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned

# For PostgreSQL  
./temporal-sql-tool -u temporal --pw temporal --pl postgres12 --db temporal update-schema -d ./schema/postgresql/v12/temporal/versioned

Production Deployment Considerations

High Availability

• Run multiple instances of each service type
• Use a load balancer for frontend service
• Configure proper health checks
• Use persistent storage (not SQLite)

Database

• Use a production-grade database (PostgreSQL, MySQL, or Cassandra)
• Configure regular backups
• Monitor database performance
• Size appropriately based on workflow volume

Security

• Configure TLS for all service communication
• Enable authentication and authorization
• Use secrets management for credentials
• Restrict network access using firewalls
• Never use --allow-no-auth in production

Monitoring

• Configure Prometheus metrics scraping
• Set up alerting for critical metrics
• Use Grafana dashboards for visualization
• Monitor service health and resource usage

Scaling

Key scaling parameters:

persistence:
  numHistoryShards: 4096  # Increase for higher throughput

Refer to Temporal’s production deployment guide for detailed recommendations.

Next Steps

Quick Start Guide

Get started quickly with Temporal Server

Architecture Documentation

Learn about Temporal Server architecture

Contributing Guide

Contribute to Temporal Server development

Production Deployment

Deploy Temporal in production