Docker Deployment

The workflow engine is distributed as a Docker image and can be deployed standalone or as part of the full neops stack.

Docker Image

docker pull quay.io/zebbra/neops-workflow-engine:latest

Tags follow the branch/release naming:

Tag	Source
`latest`	Latest stable release
`develop`	Latest development build
`main`	Latest main branch build
`x.y.z`	Specific release version

Docker Compose

The repository includes a ready-to-use docker-compose.yml that starts the development dependency stack (PostgreSQL + Monitor App):

docker compose up -d

Run the engine locally with npm run start:dev (see Setup). The base compose file only starts supporting services — the engine is not included.

Service	URL	Purpose
PostgreSQL	`localhost:5434`	Database (mapped from container port 5432)
Monitor App	http://localhost:5173	Web UI for workflow management

Configuration

All settings can be overridden via environment variables or a .env file:

Variable	Default	Description
`POSTGRES_PASSWORD`	`unsafe`	Database password
`POSTGRES_PORT`	`5434`	Host port for PostgreSQL
`MONITOR_PORT`	`5173`	Host port for the Monitor App

CMS dependency

Workflows that use acquire clauses or operate on specific entities (devices, interfaces, groups) require a running CMS. Set NEOPS_CMS_URL to point to an existing instance — either as a compose variable (when using the build override) or as a host environment variable (when running the engine locally via npm).

Building the image standalone

If you need just the Docker image without Compose:

export NPM_TOKEN=ghp_xxx

DOCKER_BUILDKIT=1 docker build \
  --secret id=npm_token,env=NPM_TOKEN \
  -t quay.io/zebbra/neops-workflow-engine:latest .

The build uses BuildKit secrets so the token is never written to image layers.

Running Migrations

The engine runs pending migrations automatically on startup.

Networking

The engine needs to reach:

PostgreSQL -- for state persistence
CMS -- for entity data and locking (GraphQL over HTTP)

Workers need to reach the engine's REST API (port 3030) for:

Worker registration and heartbeat
Function block registration
Job polling and result pushing

The Monitor App runs client-side in the browser and connects to the engine API directly (default: http://localhost:3030, configurable in the Monitor App's Settings page).

Health Check

The engine exposes a health endpoint:

curl http://localhost:3030/health/

The docker-compose.build.yml override includes a health check for the engine service. For custom deployments, configure it like this:

services:
  engine:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3030/health/"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 30s

See also: Configuration Reference for all environment variables, Setup for local development.