Skip to main content

Docker

Zigflow publishes a Docker image to the GitHub Container Registry on every release.

What you will learn​

  • How to run Zigflow using the official Docker image
  • How to connect a containerised worker to a Temporal server
  • How to configure the worker using environment variables
  • How to set up Zigflow in a Docker Compose stack

Image​

ghcr.io/mrsimonemms/zigflow

Tags:

  • latest — most recent release
  • 0.1.0 (or any version) — specific release

The binary is set as the container entrypoint. Pass run and any flags as the command.

Running the binary​

To run Zigflow without Docker, download the binary for your platform from the releases page and run it directly:

zigflow run -f workflow.yaml

Pass any flag or set the equivalent environment variable. See Deploying overview for the full connection flag reference.

Basic usage​

Mount your workflow file into the container and pass its path with -f:

docker run --rm \
  -v /path/to/workflow.yaml:/app/workflow.yaml \
  ghcr.io/mrsimonemms/zigflow \
  run -f /app/workflow.yaml \
  --temporal-address host.docker.internal:7233

Use host.docker.internal to reach a Temporal server running on your host machine. On Linux, you may need to use 172.17.0.1 or --network host instead.

Docker Compose​

A typical Compose setup runs Temporal and Zigflow together:

compose.yaml
services:
  temporal:
    image: temporalio/temporal
    command: server start-dev --ip 0.0.0.0
    ports:
      - "8233:8233"
      - "7233:7233"
    healthcheck:
      test: ["CMD-SHELL", "temporal operator cluster health"]
      interval: 10s
      timeout: 10s
      retries: 3

  worker:
    image: ghcr.io/mrsimonemms/zigflow
    command:
      - run
      - -f
      - /app/workflow.yaml
    environment:
      TEMPORAL_ADDRESS: temporal:7233
      TEMPORAL_NAMESPACE: default
      LOG_LEVEL: info
    volumes:
      - ./workflow.yaml:/app/workflow.yaml
    depends_on:
      temporal:
        condition: service_healthy

Environment variables​

The Zigflow Docker image reads the same environment variables as the CLI flags. Key variables:

VariableCLI flagDefault
TEMPORAL_ADDRESS--temporal-addresslocalhost:7233
TEMPORAL_NAMESPACE--temporal-namespacedefault
TEMPORAL_API_KEY--temporal-api-key(none)
TEMPORAL_TLS--temporal-tlsfalse
LOG_LEVEL--log-levelinfo
CLOUDEVENTS_CONFIG--cloudevents-config(none)
WORKFLOW_FILE-f(none)
DISABLE_TELEMETRY--disable-telemetry(false)

Workflow environment variables (accessed via $env in expressions) can be passed with the ZIGGY_ prefix by default:

environment:
  ZIGGY_API_BASE_URL: https://api.example.com

Inside the workflow:

endpoint: ${ $env.API_BASE_URL }

Ports​

The container exposes two ports:

PortPurpose
3000Health check (/health)
9090Prometheus metrics

Map them in Compose if needed:

ports:
  - "3000:3000"
  - "9090:9090"

Connecting to Temporal Cloud​

For Temporal Cloud, enable TLS and provide an API key:

environment:
  TEMPORAL_ADDRESS: your-namespace.tmprl.cloud:7233
  TEMPORAL_NAMESPACE: your-namespace
  TEMPORAL_TLS: "true"
  TEMPORAL_API_KEY: your-api-key

Common mistakes​

The worker cannot reach the Temporal server. Check the TEMPORAL_ADDRESS value. In Docker Compose, use the service name (temporal:7233). On a local host, use host.docker.internal:7233.

The workflow file is not found. Verify the volume mount path matches the path passed to -f.