Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 91 additions & 6 deletions docs/production-deployment/self-hosted-guide/deployment.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,32 @@ If you have Docker and Docker Compose installed, all you need to do is clone the

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](/visibility#advanced-visibility) using [Search Attributes](/search-attribute), emit metrics, and even play with the [Archival](/temporal-service/archival) feature.
The Docker images in this repo are produced using the Temporal Server [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script.
This script defaults to creating images that run all the Temporal Server services in a single process.
You can use this script as a starting point for producing your own images.

:::warning Docker Image Changes

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reference to docker compose above should go to samples server.


For example configurations and setup guidance, refer to the [samples-server repository](https://github.com/temporalio/samples-server) instead.

:::

:::tip Local Development Alternative

For local development and testing, use the Temporal CLI's built-in development server:

```bash
temporal server start-dev
```

This provides:
- A local Temporal Server with Web UI (http://localhost:8233)
- Automatic creation of the `default` Namespace
- Optional persistence with `--db-filename` for SQLite storage
- Custom Search Attributes with `--search-attribute`

See [`temporal server start-dev`](/cli/server#start-dev) for all options.

:::

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

Expand Down Expand Up @@ -74,10 +97,58 @@ docker run
temporalio/server:<tag>
```

The environment variables supported by the Temporal Docker images are documented [on Docker Hub](https://hub.docker.com/r/temporalio/auto-setup).
:::note 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](#configuration-templating) for details.

:::

The environment variables supported by the Temporal Docker images are documented [on Docker Hub](https://hub.docker.com/r/temporalio/server).
Comment on lines +102 to +113

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't seem to find this section. Does Configuration Templating actually exist?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, search redirects me to that main website


:::warning Deprecated: Auto Setup Image

Each Temporal Server release ships an [Auto Setup](https://temporal.io/blog/auto-setup) Docker image that includes an [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script.
We recommend using this script for initial schema setup of each supported database.
The `temporalio/auto-setup` Docker image is deprecated and no longer receives updates. For initial schema setup and example configurations, refer to:

- [samples-server repository](https://github.com/temporalio/samples-server) for setup examples
- Manual schema setup instructions in the [Visibility guide](/self-hosted-guide/visibility)
- The `temporal-elasticsearch-tool` in the `temporalio/admin-tools` image for Elasticsearch setup

:::

### 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](http://masterminds.github.io/sprig/) 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.

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

### Importing the Server package

Expand All @@ -93,3 +164,17 @@ This requires Go v1.19 or later, as specified in the Temporal Server [Build prer
[Temporal Helm charts](https://github.com/temporalio/helm-charts) enable you to get a Temporal Service running on [Kubernetes](https://kubernetes.io/) 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](https://github.com/temporalio/helm-charts/blob/main/README.md) about Kubernetes deployments.

:::warning 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](https://github.com/temporalio/helm-charts/releases/tag/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.

:::
10 changes: 8 additions & 2 deletions docs/production-deployment/self-hosted-guide/namespaces.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,15 @@ You can create Namespaces using:
If no Namespace is specified, SDKs and CLI use the `default` Namespace.
You must register this Namespace before using it.

When deploying with Docker Compose or the [auto-setup image](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh), the `default` Namespace is created automatically.
:::warning Deprecated: auto-setup Image

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer something more like:

### The default Namespace

If no Namespace is specified, SDKs and CLI use the `default` Namespace.
You must register this Namespace before using it. For local development, the [`temporal server start-dev`](/cli/server#start-dev) command automatically creates the `default` Namespace.


For all other deployment methods, create the `default` Namespace manually using the Temporal CLI:

```bash
temporal operator namespace create --namespace default

:::warning Deprecated: auto-setup Image

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

:::
For setup examples, refer to the samples-server repository and helm-charts repository.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/temporalio/samples-server/tree/main/compose


When deploying with [Helm charts](https://github.com/temporalio/helm-charts), create it manually:
The `temporalio/auto-setup` image is deprecated and no longer receives updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).

:::

For local development, the [`temporal server start-dev`](/cli/server#start-dev) command automatically creates the `default` Namespace.

For all other deployment methods, create the `default` Namespace manually using the Temporal CLI:

```bash
temporal operator namespace create --namespace default
Expand Down
42 changes: 37 additions & 5 deletions docs/production-deployment/self-hosted-guide/visibility.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,13 @@ Visibility data is stored in a database table called `executions_visibility` tha

- [MySQL v8.0.17 and later](https://github.com/temporalio/temporal/tree/main/schema/mysql/v8/visibility)

The following example shows how the [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script sets up your Visibility store.
:::warning Deprecated: auto-setup.sh Script

The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).
The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server/tree/main/compose).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same for similar references


:::

The following example shows how to set up your MySQL Visibility store using `temporal-sql-tool`:

```bash
#...
Expand Down Expand Up @@ -198,7 +204,13 @@ Visibility data is stored in a database table called `executions_visibility` tha

- [PostgreSQL v12 and later](https://github.com/temporalio/temporal/tree/main/schema/postgresql/v12/visibility)

The following example shows how the [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script sets up your PostgreSQL Visibility store.
:::warning Deprecated: auto-setup.sh Script

The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).

:::

The following example shows how to set up your PostgreSQL Visibility store using `temporal-sql-tool`:

```bash
#...
Expand Down Expand Up @@ -334,7 +346,13 @@ persistence:

Visibility data is stored in a database table called `executions_visibility` that must be set up according to the schemas defined (by supported versions) in https://github.com/temporalio/temporal/tree/main/schema/cassandra/visibility.

The following example shows how the [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script sets up your Visibility store.
:::warning Deprecated: auto-setup.sh Script

The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).

:::

The following example shows how to set up your Cassandra Visibility store using `temporal-cassandra-tool`:

```bash
#...
Expand Down Expand Up @@ -399,7 +417,15 @@ persistence:

**Index schema and index**

The following example shows how the [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script sets up an Elasticsearch Visibility store.
:::warning Deprecated: auto-setup.sh Script

The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates.

For Elasticsearch setup, use the `temporal-elasticsearch-tool` available in the `temporalio/admin-tools` image (version 1.30+). For examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).

:::

The following example shows how to set up an Elasticsearch Visibility store using `temporal-elasticsearch-tool`:
Comment on lines +424 to +428

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we just replace the existing examples or have them in a collapsible section?


```bash
#...
Expand Down Expand Up @@ -785,7 +811,13 @@ temporal operator search-attribute create --name="CustomSA" --type="Keyword" --n

You can also create multiple custom Search Attributes when you set up your Visibility store.

For example, the [auto-setup.sh](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) script that is used to set up your local [docker-compose Temporal Service](https://github.com/temporalio/docker-compose) creates custom Search Attributes in the Visibility store, as shown in the following code snippet from the script (for SQL databases).
:::warning Deprecated: auto-setup.sh Script

The `auto-setup.sh` script and `temporalio/auto-setup` image are deprecated and no longer receive updates. For setup examples, refer to the [samples-server repository](https://github.com/temporalio/samples-server).

:::

The following example shows how custom Search Attributes can be created during Visibility store setup (for SQL databases).

```bash
add_custom_search_attributes() {
Expand Down