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.

This page provides instructions for deploying a Temporal Service for sustained workloads that exceed what the development server is designed to handle. For local development or testing, you can use the Temporal CLI to start a local development Temporal Service.

Use Docker Compose

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

Prerequisites

• You have Docker Compose installed.
• Docker is running and the daemon is available.
• Git is installed and available.

Procedure

1. Clone the temporalio/samples-server repository.

2. Change into the compose directory.

   cd samples-server/compose

3. Run the docker compose up command. This uses the default configuration from the docker-compose.yaml file, which includes a PostgreSQL database, an Elasticsearch instance, and exposes the Temporal gRPC Frontend on port 7233.

   docker compose up

   The Temporal Service will be available at http://localhost:8233. The Temporal Web UI will be available at http://localhost:8080.

4. (Optional) Review the additional configuration options available in the samples-server repository and use docker compose up with the corresponding configuration file to try them out. The configurations include different databases, visibility stores, and TLS settings.

Use Temporal Server binaries

You can run a complete Temporal Server by deploying two Go binaries -- the core Temporal Server, and the Temporal UI Server.

Each service can be deployed separately. Refer to How to Configure a Temporal Service without a Proxy to deploy each service using systemd. If you need to run the Temporal Server behind a reverse proxy, refer to our tutorials to deploy the Temporal Service behind an Nginx reverse proxy or an Envoy edge proxy.

Configuration templating

Configuration templating is how the Temporal Server turns a template config file into the final config.yaml it runs with. It lets you reuse one template across environments by filling in values from environment variables. For example, database endpoints, TLS paths, or feature flags.

If you are not using a custom config template, you can skip this section. The default configuration is rendered automatically by the server and can be found in the config directory when you download the

Template compatibility

If you use a custom configuration template, be aware of the following:

• The server renders templates with embedded sprig, so any dockerize-specific syntax or helpers will fail
• Some template syntax differs, 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

Helm Chart configuration

When deploying with Helm charts (version 0.73.1 or later), the following configuration options control the dockerize to sprig migration:

Configuration Option	Description	Default
server.useEntrypointScript	Use entrypoint script that auto-detects dockerize vs sprig	false
server.configMapsToMount	Which config template to mount: "dockerize", "sprig", or "both"	"dockerize"
server.setConfigFilePath	Set TEMPORAL_SERVER_CONFIG_FILE_PATH env var (required for sprig)	false

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

Use 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 version compatibility

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

Helm chart versions below 0.73.1 are not compatible with server and admin-tools images version 1.30 and later. You cannot override old chart versions with newer images.