Docker

The Pipedash web server in the ghcr.io image, with SQLite or PostgreSQL. Covers example stacks, env vars and health.

Pipedash ships a web server as the image ghcr.io/hcavarsan/pipedash-web. It serves the REST API, the WebSocket at /api/v1/ws and the embedded frontend on one port.

Image

Every version tag publishes the image to the GitHub Container Registry for linux/amd64 and linux/arm64.

Tag	Example for release 0.1.1	Note
semver	`0.1.1`	Full version
major.minor	`0.1`	Moves with each patch release
sha	`sha-<short-commit>`	One tag per commit
`latest`	`latest`	Skipped when the tag name contains `-beta` or `-alpha`

docker pull ghcr.io/hcavarsan/pipedash-web:latest

The image is a scratch image with CA certificates and one static binary. It declares no exposed port and no user, so the container needs a published port. The binary listens on 127.0.0.1:8080 unless PIPEDASH_BIND_ADDR says otherwise, so a container needs PIPEDASH_BIND_ADDR set to 0.0.0.0:8080.

Environment variables

These are the variables the example compose files set, plus PIPEDASH_CORS_ALLOW_ALL.

Variable	Value in examples	Meaning
`PIPEDASH_BIND_ADDR`	`0.0.0.0:8080`	Listen address. Default `127.0.0.1:8080`.
`PIPEDASH_DATA_DIR`	`/data`	Data directory. A value starting with `/data` or `/var` also selects server mode.
`PIPEDASH_METRICS_ENABLED`	`"true"`	Not read by the current version. `general.metrics_enabled` in `config.toml` controls metrics and defaults to `true`.
`PIPEDASH_EMBEDDED_FRONTEND`	`"true"`	Serves the bundled UI. Default `true`. Only `true` or `1` enables it.
`PIPEDASH_CONFIG_PATH`	`/config/config.toml`	Config file location.
`PIPEDASH_VAULT_PASSWORD`	`<vault-password>`	Encrypts tokens in storage. Also the API bearer token.
`PIPEDASH_POSTGRES_URL`	`<postgres-url>`	PostgreSQL connection string. Postgres example only.
`GITHUB_TOKEN`	`<github-token>`	Read by `${GITHUB_TOKEN}` in `config.toml`.
`PIPEDASH_CORS_ALLOW_ALL`	not set	Allows any origin, method and header. Default `false`. Only `true` or `1` enables it. The TOML key `server.cors_allow_all` has no effect on the web server.

The sample values in the repo are not secure. A server exposed to a network needs its own vault password, Postgres password and GitHub token in place of the samples.

SQLite stack

examples/sqlite runs one container with a named volume for /data and a read-only config mount.

services:
  pipedash:
    build:
      context: ../..
      dockerfile: docker/Dockerfile
      platforms:
        - linux/amd64
    platform: linux/amd64
    ports:
      - "8080:8080"
    environment:
      PIPEDASH_BIND_ADDR: 0.0.0.0:8080
      PIPEDASH_DATA_DIR: /data
      PIPEDASH_METRICS_ENABLED: "true"
      PIPEDASH_EMBEDDED_FRONTEND: "true"
      PIPEDASH_CONFIG_PATH: /config/config.toml
      PIPEDASH_VAULT_PASSWORD: <vault-password>
      GITHUB_TOKEN: <github-token>
    volumes:
      - ./config.toml:/config/config.toml:ro
      - pipedash-data:/data
    restart: unless-stopped

volumes:
  pipedash-data:

The example config.toml defines 2 GitHub providers with token = "${GITHUB_TOKEN}" and selected repositories. It comments out the providers for GitLab, Buildkite and Jenkins.

mise run examples:sqlite:up
mise run examples:sqlite:down

up builds the image and starts the stack. down stops it and runs docker compose down -v, which deletes the pipedash-data volume.

PostgreSQL stack

examples/postgres adds a postgres:17-alpine service with a health check. The Pipedash service waits until the database reports healthy.

services:
  postgres:
    image: postgres:17-alpine
    platform: linux/amd64
    environment:
      POSTGRES_USER: pipedash
      POSTGRES_PASSWORD: <postgres-password>
      POSTGRES_DB: pipedash
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pipedash -d pipedash"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  pipedash:
    build:
      context: ../..
      dockerfile: docker/Dockerfile
      platforms:
        - linux/amd64
    platform: linux/amd64
    ports:
      - "8080:8080"
    environment:
      PIPEDASH_BIND_ADDR: 0.0.0.0:8080
      PIPEDASH_DATA_DIR: /data
      PIPEDASH_METRICS_ENABLED: "true"
      PIPEDASH_EMBEDDED_FRONTEND: "true"
      PIPEDASH_CONFIG_PATH: /config/config.toml
      PIPEDASH_VAULT_PASSWORD: <vault-password>
      PIPEDASH_POSTGRES_URL: postgres://pipedash:<postgres-password>@postgres:5432/pipedash
      GITHUB_TOKEN: <github-token>
    volumes:
      - ./config.toml:/config/config.toml:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres-data:

Its config.toml sets backend = "postgres" and connection_string = "${PIPEDASH_POSTGRES_URL}". The Postgres password appears twice, so both places need the same change. See storage backends for the backend rules.

mise run examples:postgres:up
mise run examples:postgres:down

Volumes

Volume	Mount	Holds
`pipedash-data`	`/data`	SQLite database and data directory. SQLite stack only.
`postgres-data`	`/var/lib/postgresql/data`	PostgreSQL data. Postgres stack only.
`./config.toml`	`/config/config.toml` (read-only)	Config file.

Health check

GET /api/v1/health needs no authentication and returns JSON with status, version and database.

curl http://localhost:8080/api/v1/health

status is ok when the server is ready and initializing while the token store loads. It is setup_required before the first setup and config_error when the config is invalid. The last two states add a setup_required or config_error field. See the REST API reference for the other routes.

Docker

ImageCopy Anchor Link

Environment variablesCopy Anchor Link

SQLite stackCopy Anchor Link

PostgreSQL stackCopy Anchor Link