# Temporal

> Workflow orchestration and durable execution.

- Category: Message Queues & Brokers
- Difficulty: advanced
- Components: temporal, postgres
- Tags: temporal, workflow, orchestration, durable
- Source: https://docker.recipes/messaging/temporal

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

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

## Use cases

- E-commerce order processing workflows spanning payment, inventory, shipping, and notifications
- Data engineering pipelines with complex ETL processes requiring reliability across multiple systems
- Microservices saga patterns for maintaining consistency across distributed transactions
- Infrastructure provisioning workflows coordinating cloud resources, DNS, and monitoring setup
- Customer onboarding flows involving multiple API calls, approvals, and delayed actions
- Financial transaction processing requiring strict ordering and failure handling
- Content 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

## docker-compose.yml

```yaml
services:
  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:
    image: temporalio/ui:latest
    container_name: temporal-ui
    environment:
      TEMPORAL_ADDRESS: temporal:7233
    ports:
      - "8080:8080"
    depends_on:
      - temporal
    networks:
      - temporal

  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

volumes:
  postgres_data:

networks:
  temporal:
    driver: bridge
```

## .env

```bash
DB_USER=temporal
DB_PASSWORD=changeme
```

## Usage notes

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

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

