---
title: "Install Pipelogiq with Docker"
description: "Start the server, create your administrator and application, and run a two-stage workflow with a retry."
category: "Get started"
---

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

```bash
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.

```bash
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`:

| Variable | Set it to |
| --- | --- |
| `JWT_SECRET` | The first generated value. The published example value is rejected at startup. |
| `SECRETS_ENCRYPTION_KEY` | The second generated value. Compose passes it to both server and orchestration worker. |
| `BOOTSTRAP_APPLICATION_NAME` | `local-demo` |
| `BOOTSTRAP_API_KEY` | The third generated value, on one line without quotation marks. |
| `ADMIN_EMAIL` | The email address you will use to sign in. |
| `ADMIN_PASSWORD_HASH` | Leave empty for the first-start generated password. |

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](/docs/deployment) 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

```bash
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

```bash
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.

| Surface | Local source-stack address |
| --- | --- |
| Dashboard | `http://localhost:3300` |
| Dashboard API | `http://localhost:3300/api` |
| SDK and HTTP worker API | `http://localhost:8081` |
| Worker metrics | `http://localhost:9090/metrics` |
| RabbitMQ management | `http://localhost:15672` |
| Grafana | `http://localhost:3100` |
| PostgreSQL | `localhost:5441` |

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:

```bash
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](/docs/access) 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
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:

```text
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](/docs/concepts) and [reliable execution](/docs/reliability).

## Stop and start again

```bash
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:

```bash
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:

```bash
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.