Skip to content

Commit f988db3

Browse files
alexandreromanalexandreroman
committed
Add Docker Compose support
1 parent 418cbd7 commit f988db3

3 files changed

Lines changed: 120 additions & 1 deletion

File tree

‎SKILL.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: temporal-developer
3-
description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, and Java. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns.
3+
description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, and Java. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, running Temporal with Docker Compose or Podman, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns.
44
version: 0.2.0
55
---
66

@@ -97,6 +97,7 @@ Once you've downloaded the file, extract the downloaded archive and add the temp
9797
- **`references/core/error-reference.md`** - Common error types, workflow status reference
9898
- **`references/core/interactive-workflows.md`** - Testing signals, updates, queries
9999
- **`references/core/dev-management.md`** - Dev cycle & management of server and workers
100+
- **`references/core/docker-compose.md`** - Running Temporal with Docker Compose (dev environment, workers, observability)
100101
- **`references/core/ai-patterns.md`** - AI/LLM pattern concepts
101102
- Language-specific info at `references/{your_language}/ai-patterns.md`, if available. Currently Python only.
102103

‎references/core/dev-management.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ temporal server start-dev # Start this in the background.
1010

1111
It is perfectly OK for this process to be shared across multiple projects / left running as you develop your Temporal code.
1212

13+
Alternatively, you can run Temporal as a Docker Compose service. See `references/core/docker-compose.md` for details.
14+
1315
## Worker Management Details
1416

1517
### Starting Workers

‎references/core/docker-compose.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Running Temporal with Docker Compose
2+
3+
## Overview
4+
5+
Docker Compose provides a convenient way to run a Temporal development environment as a set of containers. This is an alternative to installing the Temporal CLI locally and running `temporal server start-dev`.
6+
7+
All examples in this guide work with both **Docker Compose** and **Podman Compose**. Simply replace `docker compose` with `podman compose` in all commands. The `compose.yaml` file format is the same for both runtimes.
8+
9+
This approach is especially useful when:
10+
11+
- You want a reproducible, self-contained dev environment
12+
- You are running multiple services (workers, frontends) that connect to Temporal
13+
- You want to simulate a production-like setup locally
14+
15+
## Minimal Compose File
16+
17+
A minimal `compose.yaml` to run Temporal for development:
18+
19+
```yaml
20+
services:
21+
temporal:
22+
image: temporalio/temporal
23+
ports:
24+
- "7233:7233" # gRPC frontend (used by workers and clients)
25+
- "8233:8233" # Dev Server web UI
26+
command: server start-dev --ip 0.0.0.0
27+
healthcheck:
28+
test: ["CMD-SHELL", "temporal operator cluster health"]
29+
interval: 10s
30+
timeout: 10s
31+
retries: 3
32+
```
33+
34+
Start it with:
35+
36+
```bash
37+
docker compose up -d
38+
# or with Podman:
39+
podman compose up -d
40+
```
41+
42+
The Temporal Web UI is then available at `http://localhost:8233`.
43+
44+
## Key Ports
45+
46+
| Port | Protocol | Purpose |
47+
|------|----------|---------|
48+
| 7233 | gRPC | Frontend service — workers and clients connect here |
49+
| 8233 | HTTP | Dev Server web UI for inspecting workflows |
50+
51+
## Connecting Workers to Temporal in Docker Compose
52+
53+
Workers running as containers in the same Compose network connect to `temporal:7233` (using the service name as hostname). Workers running on the host machine connect to `localhost:7233`.
54+
55+
### Worker as a Compose Service
56+
57+
```yaml
58+
services:
59+
temporal:
60+
image: temporalio/temporal
61+
ports:
62+
- "7233:7233"
63+
- "8233:8233"
64+
command: server start-dev --ip 0.0.0.0
65+
healthcheck:
66+
test: ["CMD-SHELL", "temporal operator cluster health"]
67+
interval: 10s
68+
timeout: 10s
69+
retries: 3
70+
71+
worker:
72+
build:
73+
context: ./worker
74+
environment:
75+
- TEMPORAL_ADDRESS=temporal:7233
76+
restart: on-failure
77+
depends_on:
78+
temporal:
79+
condition: service_healthy
80+
```
81+
82+
Important points:
83+
84+
- **`depends_on` with `service_healthy`** ensures the worker does not start until Temporal is ready to accept connections. Without this, the worker will crash-loop on startup.
85+
- **`restart: on-failure`** lets the worker recover from transient errors.
86+
- **`TEMPORAL_ADDRESS`** is the standard environment variable used by Temporal SDKs and CLI to locate the Temporal frontend service.
87+
88+
## Using Podman Instead of Docker
89+
90+
Podman is a daemonless, rootless container engine that is a drop-in replacement for Docker. Podman Compose reads the same `compose.yaml` format.
91+
92+
### Usage
93+
94+
Replace `docker compose` with `podman compose` in all commands:
95+
96+
```bash
97+
podman compose up -d # Start all services
98+
podman compose down # Stop and remove all services
99+
podman compose logs -f worker # Follow worker logs
100+
podman compose ps # List running services
101+
```
102+
103+
### Podman-Specific Notes
104+
105+
- **Rootless networking**: Podman runs rootless by default. Containers in the same Compose project share a network and can reach each other by service name, just like Docker.
106+
- **`podman-compose` vs `docker compose`**: `podman-compose` is a standalone Python tool. Alternatively, if `podman` is aliased to `docker`, the `docker compose` CLI plugin also works with Podman.
107+
- **Healthchecks**: Podman supports healthchecks and `depends_on: condition: service_healthy` the same way as Docker Compose.
108+
- **Build support**: `podman compose build` uses Buildah under the hood. Dockerfiles work without modification.
109+
110+
## Tips
111+
112+
- **Always use the healthcheck** on the Temporal service and `depends_on: condition: service_healthy` on workers. Without this, workers will fail to connect on startup.
113+
- **Use `--ip 0.0.0.0`** in the Temporal dev server command so it listens on all interfaces, not just localhost. This is required for other containers to connect.
114+
- **The `temporalio/temporal` image** bundles the Temporal CLI and runs the dev server. It is meant for development, not production. For production self-hosted deployments, use the `temporalio/auto-setup` image with a real database (PostgreSQL or MySQL).
115+
- **Namespace creation**: The dev server creates a `default` namespace automatically. For custom namespaces, use `temporal operator namespace create` after the server is healthy.
116+
- **Data persistence**: By default the dev server stores data in memory. Data is lost when the container is recreated. To persist data across restarts, mount a volume for the database file or use a dedicated database service.

0 commit comments

Comments
 (0)