Skip to content

Setup

Quick Start with Docker Compose

If you want the fastest local setup for development dependencies:

git clone https://github.com/zebbra/neops-workflow-engine.git
cd neops-workflow-engine
npm install
docker compose up -d
npm run start:dev

This starts PostgreSQL and the Monitor App in the background, then runs the engine locally with hot-reload.

Service URL
Workflow Engine API http://localhost:3030
Swagger UI http://localhost:3030/api
Monitor App http://localhost:5173

Migrations run automatically on first engine start. Skip ahead to Your First Workflow.

See Docker Deployment for compose configuration variables, building the engine as a container, and production deployment.

Setup Without Docker Compose

If you prefer to manage PostgreSQL and the Monitor App yourself:

1. Clone and Install

git clone https://github.com/zebbra/neops-workflow-engine.git
cd neops-workflow-engine
npm install

2. Database

The engine requires PostgreSQL. The fastest way to get it running:

=== "Docker (recommended)"

```bash
docker run -d --name neops-postgres \
  -e POSTGRES_PASSWORD=unsafe \
  -p 5434:5432 \
  postgres:15
```

=== "Local PostgreSQL"

Ensure PostgreSQL is running on port 5434 (or configure `POSTGRES_PORT`) with a user that can create databases.

Run migrations to create the database tables (using MikroORM, the engine's database toolkit):

npx mikro-orm migration:fresh

Warning

migration:fresh drops all existing tables and recreates them. For an existing database with data you want to keep, use npx mikro-orm migration:up instead.

3. Configuration

Create a .env file in the project root or export environment variables:

POSTGRES_HOST=localhost
POSTGRES_PORT=5434
POSTGRES_USER=postgres
POSTGRES_PASSWORD=unsafe
All environment variables

See the Configuration Reference for the full list of environment variables including CMS connection, logging, and worker management settings.

4. Start the Engine

=== "Development mode (auto-reload)"

```bash
npm run start:dev
```

=== "Production mode"

```bash
npm run build
npm run start:prod
```

The engine starts on port 3030 by default. Verify it is running:

curl http://localhost:3030/health/

You should see a JSON response confirming the engine is healthy.

5. Start the Monitor App

The Monitor App is a built-in web UI for managing workflows and inspecting executions:

make run-monitor

Open http://localhost:5173 to access the Monitor App.

Note

The Monitor App is a standalone development UI that will be integrated into the neops Web Client in a future release. For now, it is the primary interface for interacting with the workflow engine during development.

Tip

If you used docker compose up in the Quick Start above, the Monitor App is already running and you can skip this step.

Get autocompletion and validation for workflow YAML files in your editor:

=== "VS Code"

Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml),
then add to `.vscode/settings.json`:

```json
{
  "yaml.schemas": {
    "http://localhost:3030/schema": "*.workflow.yaml"
  }
}
```

For offline use, point to the local schema file instead:

```json
{
  "yaml.schemas": {
    "./schema/RootWorkflow.schema.json": "*.workflow.yaml"
  }
}
```

=== "JetBrains (IntelliJ, PyCharm)"

Go to **Settings** → **Languages & Frameworks** → **Schemas and DTDs** →
**JSON Schema Mappings**. Add a mapping with URL `http://localhost:3030/schema`
and file path pattern `*.workflow.yaml`.

See the Schema Reference for more details on validation options.

Next: Your First Workflow -- deploy and execute a workflow end to end.