flowwrightdev/flowwright repository overview

⁠FlowWright

A local-first, TypeScript-native pipeline engine for building, testing, and shipping.

Swap sprawling, hard-to-test CI YAML for a typed, reusable pipeline.ts that behaves the same on your laptop, in any CI provider, and on this optional team server.

This image contains the control-plane server (API + web UI) and the execution worker. The CLI is distributed separately, on npm as @flowwright/cli⁠.

• Source: https://github.com/Flow-Wright/FlowWright⁠
• Documentation: https://docs.flowwright.dev⁠
• Website: https://flowwright.dev⁠

⁠Quick start

$ docker run -d -p 4317:4317 -v flowwright-data:/data flowwrightdev/flowwright

Open http://localhost:4317⁠.

Authentication is required by default. On first boot the server creates an administrator and writes a one-time temporary password to <dataDir>/initial-admin-password (mode 0600), also printing it to the log. Set FW_AUTH=disabled only when you explicitly want an open, no-auth development server — it removes the identity boundary entirely and every caller becomes an implicit admin.

⁠Two daemons, one image

The default command runs the server. Override it to run a worker instead:

# server (default)
$ docker run -d -p 4317:4317 -v flowwright-data:/data flowwrightdev/flowwright

# worker — no HTTP server, so the image's healthcheck can't apply to it
$ docker run -d -v flowwright-data:/data --no-healthcheck \
    flowwrightdev/flowwright /app/apps/worker/dist/main.js

⁠Running as non-root

The container runs as uid 1000 (node), not root. A new volume works with no setup — Docker initialises an empty volume from the image, ownership included.

A volume created by an earlier, root-running image needs a one-time chown before you upgrade, or the server exits with unable to open database file:

$ docker compose down                    # or: docker stop <container>
$ docker volume ls                       # compose prefixes it: <project>_data
$ docker run --rm -v flowwright_data:/data alpine chown -R 1000:1000 /data
$ docker compose up -d

For a bind mount, sudo chown -R 1000:1000 ./your-data-dir on the host. If you need to defer the migration, --user 0:0 (or user: "0:0" in compose) restores the old behaviour — set it on the server and every worker, since a root worker plus a non-root server leaves run directories the server can't clean up.

⁠Docker Compose

The published compose.yml runs an enqueue-only server (FW_WORKERS=0) plus a scalable worker pool sharing one data volume:

$ curl -O https://raw.githubusercontent.com/Flow-Wright/FlowWright/main/compose.yml
$ docker compose up -d                    # server + 1 worker
$ docker compose up -d --scale worker=4   # server + 4 workers

Pin a release with FLOWWRIGHT_VERSION=0.1.0 docker compose up -d.

⁠Tags

Built for linux/amd64 and linux/arm64.

⁠Configuration

Full reference: configuration⁠.

Port 4317 · Volume /data — the container's working directory, so the data dir lands at /data/.flowwright.

Treat that volume as sensitive: it holds execution state, logs, artifacts, cache data, and encrypted key material.

⁠Health & monitoring

Send SIGTERM for graceful shutdown — traffic, schedulers, GC, and the queue stop before state closes.

⁠Production notes

• Set FW_SECRET_KEY explicitly from a secret manager, identical across server and workers. If unset, a key is generated onto the data volume, where it sits next to the data it protects.
• Put the server behind TLS; the app serves plain HTTP on 4317.
• For more than one host, drop the shared volume: point every server and worker at the same PostgreSQL (FW_DATABASE_URL) and an S3-compatible bucket (FW_ARTIFACTS_S3_BUCKET). No shared filesystem needed.

See the self-hosting guide⁠ for fleets, backups, and retention.

⁠License

MIT — see LICENSE⁠.