Installation - Temporal Server

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)
Build from Source
Docker

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

Clone the Repository

git clone https://github.com/temporalio/temporal.git
cd temporal

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

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

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
File-Based

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

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

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

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

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.

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

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

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.

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

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

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:
  defaultStore: sqlite-default
  visibilityStore: sqlite-visibility
  numHistoryShards: 1
  datastores:
    sqlite-default:
      sql:
        pluginName: "sqlite"
        databaseName: "default"
        connectAddr: "localhost"
        connectAttributes:
          mode: "memory"
          cache: "private"

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

Getting Started

Core Concepts

Deployment

Architecture

Operations

Advanced Features

Documentation Index

​Overview

​Installation Methods

​macOS

​Linux

​Windows

​Start the Server

​Prerequisites

​Build Steps

​Build for Specific Platforms

​Using Docker Compose

​Stop Dependencies

​Persistence Configuration

​SQLite (Development Only)

​MySQL

​PostgreSQL

​Cassandra

​Server Configuration

​Configuration File

​Configuration Options

​Environment-Based Configuration

​Command-Line Flags

​Running Specific Services

​Validation and Troubleshooting

​Validate Configuration

​Validate Dynamic Configuration

​Check Server Health

​Common Issues

​Production Deployment Considerations

​High Availability

​Database

​Security

​Monitoring

​Scaling

​Next Steps

Quick Start Guide

Architecture Documentation

Contributing Guide

Production Deployment

Build docs developers (and LLMs) love

Overview

Installation Methods

macOS

Linux

Windows

Start the Server

Prerequisites

Build Steps

Build for Specific Platforms

Using Docker Compose

Stop Dependencies

Persistence Configuration

SQLite (Development Only)

MySQL

PostgreSQL

Cassandra

Server Configuration

Configuration File

Configuration Options

Environment-Based Configuration

Command-Line Flags

Running Specific Services

Validation and Troubleshooting

Validate Configuration

Validate Dynamic Configuration

Check Server Health

Common Issues

Production Deployment Considerations

High Availability

Database

Security

Monitoring

Scaling

Next Steps