Skip to main content

Deploying a Temporal Service

There are many ways to self-host a Temporal Service. The right way for you depends entirely on your use case and where you plan to run it.

For step-by-step guides on deploying and configuring Temporal, refer to our Infrastructure tutorials.

Minimum requirements​

The Temporal Server depends on a database.

Supported databases include the following:

Docker & Docker Compose​

You can run a Temporal Service in Docker containers using Docker Compose.

If you have Docker and Docker Compose installed, all you need to do is clone the temporalio/docker-compose repo and run the docker compose up command from its root.

The temporalio/docker-compose repo comes loaded with a variety of configuration templates that enable you to try all three databases that the Temporal Platform supports (PostgreSQL, MySQL, Cassandra). It also enables you to try Advanced Visibility using Search Attributes, emit metrics, and even play with the Archival feature.

Docker Image Changes

The temporalio/auto-setup image is deprecated and no longer receives updates.

For example configurations and setup guidance, refer to the samples-server repository instead.

The following commands start and run a Temporal Service in Docker using the default configuration:

git clone https://github.com/temporalio/docker-compose.git
cd docker-compose
docker compose up

Local Temporal Clients and Workers can connect to the Temporal Service running in Docker at 127.0.0.1:7233 (default connection for most SDKs) and the Temporal Web UI at 127.0.0.1:8080.

To try other configurations (different dependencies and databases), or to try a custom Docker image, follow the temporalio/docker-compose README.

Temporal Server binaries​

You can run a complete Temporal Server by deploying just two Go binaries -- the core Temporal Server, and the Temporal UI Server. Refer to our tutorial site for more details on how to deploy Temporal binaries behind an Nginx reverse proxy or an Envoy edge proxy.

Each service can also be deployed separately. For example, if you are using Kubernetes, you could have one service per pod, so they can scale independently in the future.

In Docker, you could run each service in its own container, using the SERVICES flag to specify the service:

docker run
    # persistence/schema setup flags omitted
    -e SERVICES=history \                      -- Spin up one or more: history, matching, worker, frontend
    -e LOG_LEVEL=debug,info \                           -- Logging level
    -e DYNAMIC_CONFIG_FILE_PATH=config/foo.yaml         -- Dynamic config file to be watched
    temporalio/server:<tag>
Server Image Changes

The temporalio/server image has been streamlined to include only production-essential components. The following tools have been removed:

  • temporal CLI
  • dockerize (replaced with embedded sprig templating)
  • curl
  • bash

Configuration templating now uses embedded sprig instead of dockerize. See Configuration Templating for details.

The environment variables supported by the Temporal Docker images are documented on Docker Hub.

Deprecated: Auto Setup Image

The temporalio/auto-setup Docker image is deprecated and no longer receives updates. For initial schema setup and example configurations, refer to:

Configuration Templating​

Configuration templating has changed from using the external dockerize tool to embedded sprig templating built directly into the Temporal Server binary.

What Changed​

  • Previously: dockerize processed configuration templates with custom helper functions
  • Now: sprig templating is embedded in the server binary, and the default config template is embedded (not a separate file)

Migration Notes​

If you use custom configuration templates, be aware that:

  • Some template syntax has changed (particularly .Env and default function usage)
  • Refer to the sprig documentation for supported template functions
  • Use temporal-server render-config to verify your templates render correctly

Default configuration loading now uses the embedded template instead of searching the filesystem.

Importing the Server package​

The Temporal Server is a standalone Go application that can be imported into another project.

You might want to do this to pass custom plugins or any other customizations through the Server Options. Then you can build and run a binary that contains your customizations.

This requires Go v1.19 or later, as specified in the Temporal Server Build prerequisites.

Helm charts​

Temporal Helm charts enable you to get a Temporal Service running on Kubernetes by deploying the Temporal Server services to individual pods and connecting them to your existing database and Elasticsearch instances.

The Temporal Helm charts repo contains extensive documentation about Kubernetes deployments.

Helm Chart Breaking Changes

Important compatibility requirements:

  • Existing Helm chart versions are not compatible with server and admin-tools images version 1.30 and later
  • You cannot override existing chart versions with newer images
  • Required Helm chart version: temporal-0.73.1 or later

If you are using Temporal Server images 1.30+, you must upgrade to Helm chart version 0.73.1 or later.

Note: Temporal Cloud deployments are not impacted by these changes.