Temporal

advanced

Workflow orchestration and durable execution.

Overview

Temporal is a modern workflow orchestration platform that provides durable execution guarantees for distributed applications. Originally developed at Uber as Cadence, Temporal was open-sourced in 2019 and has become the industry standard for building reliable, long-running workflows that can survive process crashes, network failures, and infrastructure outages. Unlike traditional job queues or cron jobs, Temporal maintains complete workflow state and automatically handles retries, timeouts, and failure recovery. This Docker stack combines Temporal's server components with PostgreSQL as the persistence layer, providing a complete workflow orchestration solution. PostgreSQL serves as Temporal's visibility store and event history database, offering ACID compliance and robust query capabilities essential for workflow state management. The combination delivers enterprise-grade durability with PostgreSQL's proven reliability backing Temporal's workflow execution guarantees. This stack is ideal for engineering teams building microservices architectures, data pipelines, or any distributed system requiring reliable coordination between services. Temporal's unique value proposition lies in its ability to make complex, multi-step business processes resilient by default, while PostgreSQL ensures workflow history and state are never lost, even during system failures.

Key Features

Durable workflow execution with automatic state recovery after crashes or restarts
Built-in retry logic with exponential backoff and custom retry policies
Temporal's versioning system for safe workflow code deployments without breaking running instances
Activity timeouts and heartbeats for long-running tasks with failure detection
PostgreSQL-backed event sourcing for complete workflow audit trails and replay capability
Multi-language SDK support with type-safe workflow definitions in Go, Java, Python, and TypeScript
Web UI for monitoring workflow executions, debugging failures, and inspecting workflow history
Signal and query capabilities for real-time workflow interaction and status checking

Common Use Cases

1E-commerce order processing workflows spanning payment, inventory, shipping, and notifications
2Data engineering pipelines with complex ETL processes requiring reliability across multiple systems
3Microservices saga patterns for maintaining consistency across distributed transactions
4Infrastructure provisioning workflows coordinating cloud resources, DNS, and monitoring setup
5Customer onboarding flows involving multiple API calls, approvals, and delayed actions
6Financial transaction processing requiring strict ordering and failure handling
7Content moderation workflows with human-in-the-loop approval steps and timeouts

Prerequisites

Docker Engine 20.10+ and Docker Compose v2 for container orchestration
Minimum 4GB RAM recommended (2GB for Temporal server, 1GB for PostgreSQL, 512MB for UI)
Ports 7233 (Temporal gRPC) and 8080 (Web UI) available on the host system
Understanding of workflow concepts like activities, signals, and temporal's programming model
Environment file (.env) with DB_USER and DB_PASSWORD variables configured
Familiarity with at least one Temporal SDK language for developing workflows

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  temporal: 
3    image: temporalio/auto-setup:latest
4    container_name: temporal
5    restart: unless-stopped
6    environment: 
7      DB: postgresql
8      DB_PORT: 5432
9      POSTGRES_USER: ${DB_USER}
10      POSTGRES_PWD: ${DB_PASSWORD}
11      POSTGRES_SEEDS: postgres
12    ports: 
13      - "7233:7233"
14    depends_on: 
15      - postgres
16    networks: 
17      - temporal
18
19  temporal-ui: 
20    image: temporalio/ui:latest
21    container_name: temporal-ui
22    environment: 
23      TEMPORAL_ADDRESS: temporal:7233
24    ports: 
25      - "8080:8080"
26    depends_on: 
27      - temporal
28    networks: 
29      - temporal
30
31  postgres: 
32    image: postgres:16-alpine
33    container_name: temporal-postgres
34    environment: 
35      POSTGRES_USER: ${DB_USER}
36      POSTGRES_PASSWORD: ${DB_PASSWORD}
37    volumes: 
38      - postgres_data:/var/lib/postgresql/data
39    networks: 
40      - temporal
41
42volumes: 
43  postgres_data: 
44
45networks: 
46  temporal: 
47    driver: bridge

.env Template

.env

1DB_USER=temporal
2DB_PASSWORD=changeme

Usage Notes

1Docs: https://docs.temporal.io/
2Web UI at http://localhost:8080, gRPC API on port 7233
3SDKs for Go, Java, Python, TypeScript, .NET
4Workflows survive process restarts, crashes, and deployments
5tctl CLI: tctl workflow start --workflow_type MyWorkflow
6Production-grade: used by Netflix, Uber, Stripe

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

temporal

temporal:
  image: temporalio/auto-setup:latest
  container_name: temporal
  restart: unless-stopped
  environment:
    DB: postgresql
    DB_PORT: 5432
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PWD: ${DB_PASSWORD}
    POSTGRES_SEEDS: postgres
  ports:
    - "7233:7233"
  depends_on:
    - postgres
  networks:
    - temporal

temporal-ui

temporal-ui:
  image: temporalio/ui:latest
  container_name: temporal-ui
  environment:
    TEMPORAL_ADDRESS: temporal:7233
  ports:
    - "8080:8080"
  depends_on:
    - temporal
  networks:
    - temporal

postgres

postgres:
  image: postgres:16-alpine
  container_name: temporal-postgres
  environment:
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - temporal

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  temporal:
5    image: temporalio/auto-setup:latest
6    container_name: temporal
7    restart: unless-stopped
8    environment:
9      DB: postgresql
10      DB_PORT: 5432
11      POSTGRES_USER: ${DB_USER}
12      POSTGRES_PWD: ${DB_PASSWORD}
13      POSTGRES_SEEDS: postgres
14    ports:
15      - "7233:7233"
16    depends_on:
17      - postgres
18    networks:
19      - temporal
20
21  temporal-ui:
22    image: temporalio/ui:latest
23    container_name: temporal-ui
24    environment:
25      TEMPORAL_ADDRESS: temporal:7233
26    ports:
27      - "8080:8080"
28    depends_on:
29      - temporal
30    networks:
31      - temporal
32
33  postgres:
34    image: postgres:16-alpine
35    container_name: temporal-postgres
36    environment:
37      POSTGRES_USER: ${DB_USER}
38      POSTGRES_PASSWORD: ${DB_PASSWORD}
39    volumes:
40      - postgres_data:/var/lib/postgresql/data
41    networks:
42      - temporal
43
44volumes:
45  postgres_data:
46
47networks:
48  temporal:
49    driver: bridge
50EOF
51
52# 2. Create the .env file
53cat > .env << 'EOF'
54DB_USER=temporal
55DB_PASSWORD=changeme
56EOF
57
58# 3. Start the services
59docker compose up -d
60
61# 4. View logs
62docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/temporal/run | bash

Troubleshooting

Temporal server fails to start with 'connection refused' to postgres: Ensure PostgreSQL container is healthy before Temporal starts, add health checks and longer depends_on conditions
Workflows stuck in 'Running' state indefinitely: Check activity timeouts and heartbeat configurations, verify worker processes are running and connected to the task queue
Web UI shows 'Unable to connect to server' at localhost:8080: Verify TEMPORAL_ADDRESS environment variable points to 'temporal:7233' and both containers are on the same network
PostgreSQL container exits with permission denied errors: Ensure postgres_data volume has correct ownership, try removing the volume and recreating with proper Docker user mapping
High memory usage leading to container restarts: Increase container memory limits and tune PostgreSQL shared_buffers, Temporal's caching settings may need adjustment for large workflow histories
Workflow history queries timeout in Web UI: PostgreSQL may need performance tuning with increased work_mem and effective_cache_size for handling large workflow event histories

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

temporalpostgres

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download