Plumber Platform (self-managed)

Everything needed to self-host the Plumber Platform, the CI/CD security and compliance control plane. Analysis stays in the open-source CLI, which pushes results here over native CI OIDC.

This is the v2 line: images docker.io/getplumber/platform-backend and docker.io/getplumber/platform-frontend, one version for both (pinned in the compose files), Helm chart plumber-platform. The previous product line (v1) lives in the separate repo github.com/getplumber/platform: its Helm chart plumber, its Compose install and its installer are unchanged there. The two lines are not compatible and do not share a database; there is no automated migration.

Docker Compose

Requirements: a Linux host with Docker (Compose plugin 2.20+), git, openssl, ports 80 and 443 free, a DNS record for your domain, and a GitLab instance (17.7+ recommended).

Quick start

curl -fsSL https://raw.githubusercontent.com/getplumber/plumber-platform/main/install.sh | bash

Choose Production. The installer checks prerequisites, asks for the domain, the GitLab URL, the connection scope (whole instance or one root group), the GitLab OAuth application (it prints the exact redirect URI, https://<domain>/api/v1/auth/callback, and the link to create it), the an optional copy of the Plumber CI/CD component into your GitLab (published to its CI/CD catalog, see below), the TLS method (Let's Encrypt or your own certificates), an optional private CA and the database (bundled or external). It generates the secrets, writes .env, starts the stack and configures the GitLab connection. Then open https://<domain> and sign in with GitLab as a Plumber Admin (a GitLab instance Admin, or at least Maintainer of the root group for a group connection) to finish the setup: the GitLab access token, SMTP and the licence are set in Settings.

Choose Local for a laptop install on http://localhost:3000 (no TLS).

Manual install

git clone https://github.com/getplumber/plumber-platform.git plumber-platform
cd plumber-platform
cp .env.example .env

Fill .env: DOMAIN_NAME, GITLAB_URL, PLUMBER_TOKEN_ENCRYPTION_KEY (openssl rand -hex 32, back it up: it seals every stored secret and cannot be rotated in place), PLUMBER_DB_PASSWORD and PLUMBER_REDIS_PASSWORD (openssl rand -hex 16), then pick a profile:

COMPOSE_PROFILES	CERT_RESOLVER	Meaning
letsencrypt,internal-db	le	Let's Encrypt + bundled Postgres
custom-certs,internal-db	(empty)	Your certificates in .docker/traefik/certs/plumber_fullchain.pem and plumber_privkey.pem + bundled Postgres
letsencrypt or custom-certs	as above	External Postgres: set PLUMBER_DB_HOST and friends in .env

Private CA for GitLab: drop the .pem/.crt files in .docker/ca-certificates/ and run ./scripts/ca-bundle.sh (both containers trust them).

./scripts/preflight.sh
docker compose up -d

Then configure the GitLab connection once (create an OAuth application first: redirect URI https://<domain>/api/v1/auth/callback, confidential, scope api):

read -rs -p "OAuth application secret: " PLUMBER_BOOTSTRAP_CLIENT_SECRET; echo; export PLUMBER_BOOTSTRAP_CLIENT_SECRET
docker compose exec -T -e PLUMBER_BOOTSTRAP_CLIENT_SECRET \
  backend plumber-bootstrap -base-url https://gitlab.example.com -client-id <application-id> -scope instance

Use -scope group -root-group <path> to scope to one root group. The command refuses an already-configured instance, so it is safe to retry on a fresh install.

Plumber component in your GitLab

Pipelines include the Plumber CI/CD component from gitlab.com/getplumber/plumber. When your GitLab cannot reach gitlab.com (or you want a copy you control), the installer offers to copy it; the same step runs on its own:

read -rs -p "GitLab token: " PLUMBER_COMPONENT_TOKEN; echo; export PLUMBER_COMPONENT_TOKEN
./scripts/component-mirror.sh --gitlab-url https://gitlab.example.com --group my-group

It creates or reuses my-group/plumber (with the description the catalog requires), copies every branch and tag, flags the project as a CI/CD catalog project, runs the release pipeline on the latest tag and verifies the version is in the catalog before reporting Component published. The token (api scope, Owner of the group or instance Admin) is read from the environment for this run only. A runner able to pull registry.gitlab.com/gitlab-org/release-cli must be available to the project. Then, in Plumber, an Admin sets Settings > Component to my-group/plumber.

Update, backup, restore

./scripts/update.sh            # pulls the repo (the new image tags come with it) and restarts
./scripts/update.sh --component # same, then refreshes and publishes the component copy
./scripts/backup.sh 18         # database dump + .env (+ CA files) into backups/, optional S3 upload
./scripts/restore.sh 18 <file> # the reverse

Every release pins both images to one version. Upgrades are sequential and additive (the backend migrates the database on boot); rolling back is checking out the previous release tag (git checkout vX.Y.Z) and docker compose up -d. Never downgrade the database by hand.

Kubernetes (Helm)

helm repo add plumber-platform https://getplumber.github.io/plumber-platform
helm repo update
helm upgrade --install plumber plumber-platform/plumber-platform -n plumber --create-namespace -f values.yaml

See charts/plumber-platform/README.md for the minimal values (one ingress host serves both apps), the secrets, the bundled or external Postgres and Redis, the private CA options and the first-run bootstrap (manual command or the post-install Job).

Releases

Each release is a git tag vX.Y.Z with a GitHub Release carrying the changelog and the packaged chart; latest.json is what installs poll for the update banner. releases/ holds the notes.

Legacy v1

The previous product line (v1) lives in the separate repo github.com/getplumber/platform: its Helm chart plumber, its Compose install and its installer are unchanged there. The two lines are not compatible and do not share a database; there is no automated migration.

Contributions

You are welcome to help us improve this repository! Open an Issue or create a Pull Request from your fork.