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