-
Notifications
You must be signed in to change notification settings - Fork 292
docs: update for Docker image restructuring and deprecations #4158
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
|
||
| 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: | ||
|
|
||
|
|
@@ -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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
|
||
|
|
@@ -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. | ||
|
|
||
| ::: | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would prefer something more like: :::warning Deprecated: auto-setup Image The ::: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
|
|
||
| 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 | ||
|
|
||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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). | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||||||
| #... | ||||||
|
|
@@ -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 | ||||||
| #... | ||||||
|
|
@@ -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 | ||||||
| #... | ||||||
|
|
@@ -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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||||||
| #... | ||||||
|
|
@@ -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() { | ||||||
|
|
||||||
There was a problem hiding this comment.
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.