Install Pipelogiq with Docker

This guide installs the complete local control plane and runs a real workflow through its HTTP worker protocol. It follows the current repository configuration, whose VERSION is 0.5.0. Source builds work from the checkout; published v0.5.0 image availability must be checked before choosing registry deployment.

What you need

• Git, Docker Engine or Docker Desktop, and Docker Compose v2.
• A terminal with Bash, OpenSSL, curl, and jq. The included workflow verification script uses curl and jq.
• Free local ports 3300, 8081, 5441, 5672, 15672, 3100, 3200, 4317, 4318, and 9090 for the source stack.

You do not need Go, Node.js, or a language SDK for this Docker walkthrough. Docker builds the application and migration images. Run the following commands from one terminal on a development machine.

1. Get the source

git clone https://github.com/pipelogiq/pipelogiq.git
cd pipelogiq
cat VERSION
docker compose version
docker network inspect pipelogiq >/dev/null 2>&1 || docker network create pipelogiq

All supplied Compose files share the external pipelogiq network. The files also use fixed container names: stop another Pipelogiq stack before starting this one.

2. Configure the first application and administrator

Copy the example only for a new checkout. Keep an existing configuration when upgrading.

cp .env.example .env
chmod 600 .env
openssl rand -base64 48
openssl rand -base64 32
openssl rand -hex 32

The three commands generate, in order, a session signing secret, an integration encryption key, and an application API key. Save them in your password manager and edit .env:

Keep the other example settings for this local walkthrough. The supplied source stack uses development PostgreSQL, RabbitMQ, and Grafana credentials and publishes their ports. Use deployment guidance before running on a shared or internet-accessible host.

On the first start, bootstrap creates the application and stores a hash of its API key. It then creates the administrator and assigns applications that have no members. The bootstrap key is not printed in logs. Reusing the same application name later does not rotate, recreate, or re-enable that application's key.

3. Build and start

docker compose --env-file .env -f infra/compose/docker-compose.build.yml up --build -d
docker compose --env-file .env -f infra/compose/docker-compose.build.yml ps -a
docker compose --env-file .env -f infra/compose/docker-compose.build.yml logs --tail=100 pipelogiq-migrate

The stack starts PostgreSQL, RabbitMQ, Tempo, Grafana, a one-shot migration service, the combined dashboard/API container, and the orchestration worker. The app waits for successful migrations and healthy infrastructure. The orchestration worker waits for the app.

Expected result: pipelogiq-migrate exits successfully with code 0; the long-running app, database, broker, and worker become healthy. The migration container being stopped after success is normal. A failed migration must be resolved before the app can start.

4. Check the endpoints

curl -fsS http://localhost:3300/api/healthz
curl -fsS http://localhost:8081/healthz
curl -fsS http://localhost:3300/api/version
curl -fsS http://localhost:9090/metrics

Health endpoints confirm the HTTP services respond. The workflow test below verifies that the database, broker, execution dispatcher, and result processing work together.

Inside the app container, nginx listens on 8080 and proxies /api and /ws to the internal API on 8088. Port 8088 is not published. API metrics are a separate listener, normally 9091 inside that container; they are not served under /api/metrics.

5. Sign in

Retrieve the generated administrator password from your local startup log:

docker logs pipelogiq-app 2>&1 | rg 'one-time administrator password'

If ripgrep is not installed, use grep 'one-time administrator password' instead. This line contains a credential: read it locally rather than sharing the full log.

Open http://localhost:3300, sign in using ADMIN_EMAIL and that password, then change it under Account → Password. Confirm local-demo is available under Settings → API keys. There is no shared default dashboard password.

The password is generated only when the account is first created. An existing installation does not print another password on restart. See access management for account recovery and membership behavior.

6. Run a workflow through a temporary HTTP worker

The orchestration worker shipped in Compose dispatches stages and processes results. Your application worker executes business handlers. For this walkthrough, the repository's smoke script acts as an application worker, so no SDK installation is needed:

bash scripts/http-worker-smoke.sh

The script reads the bootstrap API key from .env, registers a temporary handler, creates a two-stage pipeline, deliberately fails its first attempt, then succeeds on retry and completes the second stage. It submits results before acknowledging deliveries and shuts down its worker registration afterward.

Expected final output has this shape, with your generated run ID:

PASS: pipeline … Completed, first stage retried once, both stages Completed

Open Pipelines, select http-worker-smoke, and inspect Stages, Logs, Context, and All data. The first stage should show a retry and both stages should be Completed. This verifies execution and recovery from a reported failure, rather than only that a port is open.

For your own workload, start a .NET, Java, or custom HTTP worker that registers the exact handler names used by your definition. Continue with workflow concepts and reliable execution.

Stop and start again

docker compose --env-file .env -f infra/compose/docker-compose.build.yml down
docker compose --env-file .env -f infra/compose/docker-compose.build.yml up -d

The normal down command preserves named database volumes. Do not add --volumes when you want to keep workflows and accounts. The source stack is for local evaluation; use the registry deployment configuration and a backup plan for persistent service operation.

Use prebuilt images instead

The registry configuration targets these image tags: ghcr.io/pipelogiq/pipelogiq-app:v0.5.0, pipelogiq-worker:v0.5.0, and pipelogiq-migrate:v0.5.0. Repository version metadata does not prove the tags have been published. Check them before switching:

docker manifest inspect ghcr.io/pipelogiq/pipelogiq-app:v0.5.0 >/dev/null
docker manifest inspect ghcr.io/pipelogiq/pipelogiq-worker:v0.5.0 >/dev/null
docker manifest inspect ghcr.io/pipelogiq/pipelogiq-migrate:v0.5.0 >/dev/null

If all are available, use the same bootstrap procedure, stop any source stack, set OTEL_EXPORTER_OTLP_ENDPOINT= in .env unless you have a collector, and run:

PIPELOGIQ_VERSION=v0.5.0 docker compose --env-file .env -f infra/compose/docker-compose.registry.yml pull
PIPELOGIQ_VERSION=v0.5.0 docker compose --env-file .env -f infra/compose/docker-compose.registry.yml up -d

Registry Compose publishes only dashboard port 3300 and external API port 8081. Metrics, database, broker, and management ports stay on the Docker network. Tempo and Grafana require --profile observability; configure the exporter endpoint when enabling them. If the tag is unavailable, use the source-build path above.