This page introduces Zyra’s official container images, when to use each, and practical usage examples.

Images at a Glance

• ghcr.io/noaa-gsl/zyra (CLI)

  • General-purpose CLI image; does not auto-start anything.

  • Includes ffmpeg; includes wgrib2 by default (built from source).

  • ENTRYPOINT: zyra

  • Healthcheck: zyra --version

  • Best for: ad-hoc local runs, CI jobs, invoking the API process explicitly.

• ghcr.io/noaa-gsl/zyra-scheduler (Watcher)

  • Long-running scheduler that watches a workflows directory and executes them.

  • Includes ffmpeg; wgrib2 is optional (not included by default).

  • ENTRYPOINT: zyra run /workflows --watch

  • Healthcheck: zyra --version

  • Best for: daemonized workloads in Docker/Kubernetes.

Tags

• vX.Y.Z (matches the GitHub release tag)

• latest (only for non-prerelease tags)

• sha-… (content-addressed)

Which Image Should I Use?

• Need a general CLI to run one-off commands or CI? Use zyra.

• Need a long-running process watching workflow YAMLs? Use zyra-scheduler.

• Need to run the HTTP API? Use zyra and start the API explicitly (examples below).

Common Volumes and Environment

• Volumes

  • /workflows: mount your workflow YAMLs here (read-only is recommended for scheduler).

  • /data: outputs, logs, and artifacts (also exposed via DATA_DIR=/data).

• Common envs

  • DATA_DIR=/data (default inside the images)

  • LOG_LEVEL=info (override as needed)

  • TZ=UTC (optional)

Quick Start

CLI (help and one-off)

# Show help
docker run --rm ghcr.io/noaa-gsl/zyra:latest --help

# Run a visualize command
mkdir -p data

docker run --rm \
  -v "$(pwd)/data:/data" \
  ghcr.io/noaa-gsl/zyra:latest visualize static --help

Scheduler (watch a workflows directory)

mkdir -p workflows data

docker run -d \
  --name zyra-scheduler \
  -v "$(pwd)/workflows:/workflows:ro" \
  -v "$(pwd)/data:/data" \
  -e LOG_LEVEL=info \
  ghcr.io/noaa-gsl/zyra-scheduler:latest

API (explicitly run the server from the CLI image)

# Bind to all interfaces, require an API key
mkdir -p data

docker run --rm \
  -p 8000:8000 \
  -e ZYRA_API_KEY=change-me \
  -v "$(pwd)/data:/data" \
  ghcr.io/noaa-gsl/zyra:latest api serve --host 0.0.0.0 --port 8000

Build-time Options

Both images accept these build args for customization (when building your own):

• ZYRA_VERSION (default latest): pin to a specific Zyra PyPI version.

• ZYRA_EXTRAS (default varies): install pip extras, e.g. connectors,processing,visualization.

• WITH_WGRIB2:

  • CLI image default: source (includes wgrib2 built from source).

  • Scheduler default: none (omit wgrib2 to keep the image lean).

  • Supported values: source (build from source), apt (install from Debian), none (exclude).

• WGRIB2_URL and WGRIB2_SHA256 (when WITH_WGRIB2=source): tarball URL and optional checksum verification.

• WITH_FFMPEG (scheduler only; default true): include ffmpeg.

Examples

# CLI image with default extras and source-built wgrib2
docker build -f docker/zyra/Dockerfile \
  --build-arg ZYRA_VERSION=latest \
  --build-arg WITH_WGRIB2=source \
  -t ghcr.io/noaa-gsl/zyra:custom .

# Scheduler image with wgrib2 omitted (default)
docker build -f docker/zyra-scheduler/Dockerfile \
  --build-arg ZYRA_VERSION=latest \
  --build-arg WITH_WGRIB2=none \
  -t ghcr.io/noaa-gsl/zyra-scheduler:custom .

# Scheduler with source-built wgrib2
docker build -f docker/zyra-scheduler/Dockerfile \
  --build-arg WITH_WGRIB2=source \
  --build-arg WGRIB2_URL=https://ftp.cpc.ncep.noaa.gov/wd51we/wgrib2/wgrib2.tgz \
  --build-arg WGRIB2_SHA256=<sha256sum> \
  -t ghcr.io/noaa-gsl/zyra-scheduler:wgrib2 .

docker-compose Examples

CLI image

# docker/zyra/docker-compose.yml
services:
  zyra:
    image: ghcr.io/noaa-gsl/zyra:latest
    command: ["--help"]
    volumes:
      - ../../data:/data
    healthcheck:
      test: ["CMD", "zyra", "--version"]
      interval: 30s
      timeout: 5s
      retries: 3

Scheduler image

# docker/zyra-scheduler/docker-compose.yml
services:
  zyra-scheduler:
    image: ghcr.io/noaa-gsl/zyra-scheduler:latest
    volumes:
      - ../../workflows:/workflows:ro
      - ../../data:/data
    environment:
      LOG_LEVEL: info
    healthcheck:
      test: ["CMD", "zyra", "--version"]
      interval: 30s
      timeout: 5s
      retries: 3

Troubleshooting

• Permissions: images run as a non-root user. If you see write errors on bind mounts, use --user $(id -u):$(id -g) or set user: in compose.

• wgrib2 not found: the scheduler image excludes wgrib2 by default; build with WITH_WGRIB2=source|apt if needed.

• API 401: set ZYRA_API_KEY and include it via the X-API-Key header (configurable with API_KEY_HEADER).

• Large outputs: mount a persistent volume at /data and set DATA_DIR=/data (default inside images).