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

# 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

<Tabs>
  <Tab title="Temporal CLI (Recommended)">
    The easiest way to install and run Temporal Server for development.

    ### macOS

    ```bash theme={null}
    brew install temporal
    ```

    ### Linux

    Download the latest release from the [Temporal CLI releases page](https://github.com/temporalio/cli/releases):

    ```bash theme={null}
    # 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](https://github.com/temporalio/cli/releases) or use a package manager like Scoop.

    ### Start the Server

    ```bash theme={null}
    temporal server start-dev
    ```
  </Tab>

  <Tab title="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

    <Note>
      The minimum required Go version is specified in the `go.mod` file in the repository.
    </Note>

    ### Build Steps

    <Steps>
      <Step title="Clone the Repository">
        ```bash theme={null}
        git clone https://github.com/temporalio/temporal.git
        cd temporal
        ```
      </Step>

      <Step title="Build the Server">
        For the first build, use the default `make` command to install dependencies and build all binaries:

        ```bash theme={null}
        make
        ```

        For subsequent builds, you can build just the binaries:

        ```bash theme={null}
        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
      </Step>

      <Step title="Verify the Build">
        ```bash theme={null}
        ./temporal-server --version
        ```
      </Step>
    </Steps>

    ### Build for Specific Platforms

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

  <Tab title="Docker">
    Run Temporal Server using Docker containers.

    ### Using Docker Compose

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

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

    ```bash theme={null}
    make stop-dependencies
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="In-Memory">
    ```bash theme={null}
    # 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
    ```

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

  <Tab title="File-Based">
    ```bash theme={null}
    # 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.
  </Tab>
</Tabs>

### MySQL

Recommended for production deployments with moderate scale.

<Steps>
  <Step title="Start MySQL">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Install Schema">
    ```bash theme={null}
    make install-schema-mysql
    ```

    This command:

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

    <Note>
      You can customize database names using environment variables:

      ```bash theme={null}
      TEMPORAL_DB=my_temporal VISIBILITY_DB=my_visibility make install-schema-mysql
      ```
    </Note>
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    make start-mysql

    # Or directly:
    ./temporal-server --env development-mysql8 --allow-no-auth start
    ```
  </Step>
</Steps>

### PostgreSQL

Recommended for production deployments, offers excellent performance and reliability.

<Steps>
  <Step title="Start PostgreSQL">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Install Schema">
    ```bash theme={null}
    make install-schema-postgresql
    ```

    Default credentials:

    * **User**: `temporal`
    * **Password**: `temporal`

    To use custom credentials:

    ```bash theme={null}
    SQL_USER=myuser SQL_PASSWORD=mypassword make install-schema-postgresql
    ```
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    make start-postgresql

    # Or directly:
    ./temporal-server --env development-postgres12 --allow-no-auth start
    ```
  </Step>
</Steps>

### Cassandra

Best for large-scale deployments requiring horizontal scalability.

<Steps>
  <Step title="Start Cassandra">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Install Schema">
    With Elasticsearch for advanced visibility:

    ```bash theme={null}
    make install-schema-cass-es
    ```

    Without Elasticsearch:

    ```bash theme={null}
    ./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
    ```
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    make start-cass-es

    # Or directly:
    ./temporal-server --env development-cass-es --allow-no-auth start
    ```
  </Step>
</Steps>

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

```bash theme={null}
./temporal-server --config-file /path/to/config.yaml start
```

### Configuration Options

Key configuration sections:

<CodeGroup>
  ```yaml Persistence theme={null}
  persistence:
    defaultStore: sqlite-default
    visibilityStore: sqlite-visibility
    numHistoryShards: 1
    datastores:
      sqlite-default:
        sql:
          pluginName: "sqlite"
          databaseName: "default"
          connectAddr: "localhost"
          connectAttributes:
            mode: "memory"
            cache: "private"
  ```

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

  ```yaml Logging theme={null}
  log:
    stdout: true
    level: info  # debug, info, warn, error
  ```

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

### Environment-Based Configuration

For legacy configuration style using environment variables:

```bash theme={null}
./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:

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

```bash theme={null}
# Render and validate configuration
./temporal-server --config-file config.yaml render-config
```

### Validate Dynamic Configuration

```bash theme={null}
./temporal-server validate-dynamic-config config/dynamicconfig/development-sql.yaml
```

### Check Server Health

```bash theme={null}
# List namespaces
temporal operator namespace list

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

### Common Issues

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Port already in use">
    Check if another Temporal instance is running:

    ```bash theme={null}
    lsof -i :7233
    ```

    Change ports in configuration file if needed.
  </Accordion>

  <Accordion title="Authorization errors">
    For development, use the `--allow-no-auth` flag:

    ```bash theme={null}
    ./temporal-server --config-file config.yaml --allow-no-auth start
    ```

    For production, configure proper authorization in the config file.
  </Accordion>

  <Accordion title="Schema version mismatch">
    Update the schema to the latest version:

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

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

```yaml theme={null}
persistence:
  numHistoryShards: 4096  # Increase for higher throughput
```

Refer to [Temporal's production deployment guide](https://docs.temporal.io/self-hosted-guide) for detailed recommendations.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Get started quickly with Temporal Server
  </Card>

  <Card title="Architecture Documentation" icon="sitemap" href="https://github.com/temporalio/temporal/blob/main/docs/architecture/README.md">
    Learn about Temporal Server architecture
  </Card>

  <Card title="Contributing Guide" icon="code-pull-request" href="https://github.com/temporalio/temporal/blob/main/CONTRIBUTING.md">
    Contribute to Temporal Server development
  </Card>

  <Card title="Production Deployment" icon="server" href="https://docs.temporal.io/self-hosted-guide">
    Deploy Temporal in production
  </Card>
</CardGroup>