diff --git a/compose/README.md b/compose/README.md index e206516..6433160 100644 --- a/compose/README.md +++ b/compose/README.md @@ -7,70 +7,88 @@ There are a variety of docker-compose files, each utilizing a different set of d To use these files, you must first have the following installed: -- [Docker](https://docs.docker.com/engine/installation/) -- [docker-compose](https://docs.docker.com/compose/install/) +- [Docker](https://docs.docker.com/engine/install/) (includes Docker Compose) ## How to use The following steps will run a local instance of the Temporal Server using the default configuration file (`docker-compose.yml`): 1. Clone this repository. -2. Change directory into the root of the project. -3. Run the `docker-compose up` command. +2. Change directory into the `compose` folder. +3. Run the `docker compose up` command. ```bash git clone https://github.com/temporalio/samples-server.git cd samples-server/compose -docker-compose up +docker compose up ``` -> ⚠️ If you are on an M1 Mac, note that Temporal v1.12 to v1.14 had fatal issues with ARM builds. v1.14.2 onwards should be fine for M1 Macs. - After the Server has started, you can open the Temporal Web UI in your browser: [http://localhost:8080](http://localhost:8080). -You can also interact with the Server using a preconfigured CLI (tctl). -First create an alias for `tctl`: +To stop and remove containers and volumes: + +```bash +docker compose down -v +``` + +You can also interact with the Server using the [Temporal CLI](https://docs.temporal.io/cli). + +To install the Temporal CLI: ```bash -alias tctl="docker exec temporal-admin-tools tctl" +# macOS (Homebrew) +brew install temporal + +# Other platforms - see https://docs.temporal.io/cli#install ``` -The following is an example of how to register a new namespace `test-namespace` with 1 day of retention: +The following is an example of how to create a new namespace `test-namespace` with 1 day of retention: ```bash -tctl --ns test-namespace namespace register -rd 1 +temporal operator namespace create --namespace test-namespace --retention 1d ``` -You can find our `tctl` docs on [docs.temporal.io](https://docs.temporal.io/docs/system-tools/tctl/). +Get started building Workflows with the SDK samples: + +- [Go](https://github.com/temporalio/samples-go) +- [Java](https://github.com/temporalio/samples-java) +- [Python](https://github.com/temporalio/samples-python) +- [TypeScript](https://github.com/temporalio/samples-typescript) +- [.NET](https://github.com/temporalio/samples-dotnet) +- [PHP](https://github.com/temporalio/samples-php) +- [Ruby](https://github.com/temporalio/samples-ruby) -Get started building Workflows with a [Go sample](https://github.com/temporalio/samples-go), [Java sample](https://github.com/temporalio/samples-java), or write your own using one of the [SDKs](https://docs.temporal.io/docs/sdks-introduction). +For the most up-to-date SDK references, see [https://docs.temporal.io/develop](https://docs.temporal.io/develop). -### Other configuration files +## Other configuration files The default configuration file (`docker-compose.yml`) uses a PostgreSQL database, an Elasticsearch instance, and exposes the Temporal gRPC Frontend on port 7233. The other configuration files in the repo spin up instances of the Temporal Server using different databases and dependencies. -For example you can run the Temporal Server with MySQL and Elastic Search with this command: +For example you can run the Temporal Server with MySQL and Elasticsearch with this command: ```bash -docker-compose -f docker-compose-mysql-es.yml up +docker compose -f docker-compose-mysql-es.yml up ``` Here is a list of available files and the dependencies they use. -| File | Description | -|----------------------------------------|---------------------------------------------------------------| -| docker-compose.yml | PostgreSQL and Elasticsearch (default) | -| docker-compose-tls.yml | PostgreSQL and Elasticsearch with TLS | -| docker-compose-postgres.yml | PostgreSQL | -| docker-compose-cass-es.yml | Cassandra and Elasticsearch | -| docker-compose-mysql.yml | MySQL | -| docker-compose-mysql-es.yml | MySQL and Elasticsearch | -| docker-compose-postgres-opensearch.yml | PostgreSQL and OpenSearch | -| docker-compose-multirole.yml | PostgreSQL and Elasticsearch with mult-role Server containers | +| File | Description | +|----------------------------------------|----------------------------------------------------------------| +| docker-compose-dev.yml | Development server with local file storage (UI on port 8233) | +| docker-compose.yml | PostgreSQL and Elasticsearch (default) | +| docker-compose-tls.yml | PostgreSQL and Elasticsearch with TLS | +| docker-compose-postgres.yml | PostgreSQL | +| docker-compose-cass-es.yml | Cassandra and Elasticsearch | +| docker-compose-mysql.yml | MySQL | +| docker-compose-mysql-es.yml | MySQL and Elasticsearch | +| docker-compose-postgres-opensearch.yml | PostgreSQL and OpenSearch | +| docker-compose-multirole.yaml | PostgreSQL and Elasticsearch with multi-role Server containers | -### Using multi-role configuration +## Using multi-role configuration -First install the loki plugin (this is one time operation) +The `docker-compose-multirole.yaml` configuration runs each Temporal service separately and includes Prometheus and Grafana with [Server and SDK dashboards](https://github.com/temporalio/dashboards). + +First install the Loki plugin (this is a one-time operation) ```bash docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions ``` @@ -87,73 +105,16 @@ Some exposed endpoints: - http://localhost:9090/targets - Prometheus targets - http://localhost:8000/metrics - Server metrics -### Using the web interface - -`docker-compose.yml` includes the Temporal Web UI. - -If you run command: - -```bash -docker-compose up -``` - -You access the Temporal Web UI at http://localhost:8080. - -### Enabling metrics (with Grafana and Prometheus) - -We maintain two example docker-compose setups with server metrics enabled, and Prometheus and Grafana with [our Server and SDK dashboards](https://github.com/temporalio/dashboards): - -- https://github.com/tsurdilo/my-temporal-dockercompose -- https://github.com/temporalio/background-checks - -### Use a custom image configuration +## Production deployments -If you want, you can even use a custom Docker image of the Temporal Server. +These docker-compose setups are intended for local development and testing. For production deployments: -Clone the main Temporal Server repo: [https://github.com/temporalio/temporal](https://github.com/temporalio/temporal): - -```bash -git clone https://github.com/temporalio/temporal.git -``` - -In the following command, replace **** and **** to build the custom Docker image: - -```bash -git checkout -docker build . -t temporalio/server: --build-arg TARGET=server -``` - -Next, in the `docker-compose.yml` file, replace the `TEMPORAL_VERSION` value in the `.env` file with ****. - -Then run the `docker-compose up` command: - -```bash -docker-compose up -``` - -## Using Temporal docker images in production - -These docker-compose setups use the `temporalio/server` image with a separate initialization step to set up database schemas. The `temporal-admin-tools` service runs once to create and initialize the database schema, then the `temporal` service starts using `temporalio/server`. - -In a typical production setting, dependencies such as `cassandra` or `elasticsearch` are managed/started independently of the Temporal server, and schemas are set up as part of your deployment process rather than at startup. - -To use the `temporalio/server` container in a production setting, use the following command: - -```plain -docker run -e CASSANDRA_SEEDS=10.x.x.x -- csv of Cassandra server ipaddrs - -e KEYSPACE= -- Cassandra keyspace - -e VISIBILITY_KEYSPACE= -- Cassandra visibility keyspace - -e SKIP_SCHEMA_SETUP=true -- do not setup Cassandra schema during startup - -e NUM_HISTORY_SHARDS=1024 \ -- Number of history shards - -e SERVICES=history,matching \ -- Spin-up only the provided services - -e LOG_LEVEL=debug,info \ -- Logging level - -e DYNAMIC_CONFIG_FILE_PATH=config/foo.yaml -- Dynamic config file to be watched - temporalio/server: -``` +- **Kubernetes**: Use the [Temporal Helm Charts](https://github.com/temporalio/helm-charts) repository +- **Schema setup**: Reference the [setup scripts](./scripts/) in this repository for database schema initialization examples ## Server Configuration Templates -The Temporal Server uses a base configuration template that defines the structure for persistence, visibility, and other settings. +The Temporal Server uses a base configuration template that defines the structure for persistence, visibility, and other settings. These templates use [Sprig](https://masterminds.github.io/sprig/) for templating, which provides functions for string manipulation, environment variable access, and more. ### Configuration template location by version @@ -177,4 +138,3 @@ The docker-compose files in this repository work with both pre-v1.30 and v1.30+ 3. **Schema management**: Setup scripts detect and use new tools when available, with fallback to legacy methods For customizing server configuration beyond environment variables, refer to the appropriate template file for your server version. - diff --git a/compose/docker-compose-dev.yml b/compose/docker-compose-dev.yml new file mode 100644 index 0000000..e074929 --- /dev/null +++ b/compose/docker-compose-dev.yml @@ -0,0 +1,13 @@ +services: + temporal: + image: temporalio/temporal:latest + container_name: temporal + ports: + - 7233:7233 + - 8233:8233 + volumes: + - temporal-data:/data + command: server start-dev --ip 0.0.0.0 --db-filename /data/temporal.db + +volumes: + temporal-data: diff --git a/compose/docker-compose-multirole.yaml b/compose/docker-compose-multirole.yaml index c95bcfb..d38e857 100644 --- a/compose/docker-compose-multirole.yaml +++ b/compose/docker-compose-multirole.yaml @@ -372,8 +372,6 @@ services: target: 13133 - published: 4317 target: 4317 - - published: 55670 - target: 55670 depends_on: - jaeger-all-in-one networks: