Docker compose

Run the interactive installer on your server:

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

Choose “Production” when prompted. The installer will guide you through:

1. Domain name configuration
2. GitLab OIDC application setup
3. TLS certificate method selection
4. Database: internal PostgreSQL or your own external database
5. Secrets: automatically generated

At the end, the installer will start Plumber for you.

git clone https://github.com/getplumber/platform.git plumber-platform
cd plumber-platform
./install.sh

Step 1: Setup your environment

Clone the repository on your server

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

Create your configuration file

cp .env.example .env
cat versions.env >> .env

Step 2: Configure Organization

In your .env file:

• If you want to connect Plumber to a specific GitLab group only: add the group path as defined in GitLab in the ORGANIZATION variable (to run the onboarding, you must be at least Maintainer in this group). On GitLab.com or non‑self‑hosted instances, this path may differ from the display name of the group, and GitLab can append extra characters to make it unique. Check the group settings (or the GitLab API full_path) to copy the exact value.

  ORGANIZATION="<group-path>"

• If you want to connect Plumber to the whole GitLab instance: let the ORGANIZATION variable empty (to run the onboarding, you must be a GitLab instance Admin)

  ORGANIZATION=""

Step 3: Configure Domain name and GitLab URL

Edit the .env file by updating value of DOMAIN_NAME and JOBS_GITLAB_URL variables

DOMAIN_NAME="<your_plumber_domain>"
JOBS_GITLAB_URL="https://<url_of_your_gitlab_instance>"

DOMAIN_NAME="plumber.mydomain.com"
JOBS_GITLAB_URL="https://gitlab.mydomain.com"

Step 4: Configure GitLab OIDC

Plumber uses GitLab as an OAuth2 provider to authenticate users.

Create an application on your GitLab instance. Open any group and navigate to Settings > Applications.

Create an application with the following information:

1. Name: Plumber
2. Redirect URI: https://<your_plumber_domain>/api/auth/gitlab/callback
3. Confidential: true (keep the box checked)
4. Scopes: api

Click Save Application, then copy the Application ID and Secret into your .env file:

GITLAB_OAUTH2_CLIENT_ID="<application-id>"
GITLAB_OAUTH2_CLIENT_SECRET="<application-secret>"

Step 5: Generate secrets

Generate random secrets and set them in your .env file:

sed -i."" "s/^SECRET_KEY=.*/SECRET_KEY=\"$(openssl rand -hex 32)\"/" .env
sed -i."" "s/^JOBS_DB_PASSWORD=.*/JOBS_DB_PASSWORD=\"$(openssl rand -hex 16)\"/" .env
sed -i."" "s/^JOBS_REDIS_PASSWORD=.*/JOBS_REDIS_PASSWORD=\"$(openssl rand -hex 16)\"/" .env

Step 6: Configure deployment profile

Option A — Let’s Encrypt (automatic certificates):

COMPOSE_PROFILES="letsencrypt,internal-db"
CERT_RESOLVER="le"

No further action needed! Certificates will be automatically generated at first launch.

Option B — Custom certificates:

COMPOSE_PROFILES="custom-certs,internal-db"
CERT_RESOLVER=""

Copy your certificate files:

cp /path/to/your/fullchain.pem .docker/traefik/certs/plumber_fullchain.pem
cp /path/to/your/privkey.pem .docker/traefik/certs/plumber_privkey.pem

If you are using an external PostgreSQL database, remove ,internal-db from COMPOSE_PROFILES and configure your database connection by uncommenting and updating the following variables in your .env file:

JOBS_DB_HOST="your-db-host"
JOBS_DB_PORT="5432"
JOBS_DB_USER="your-db-user"
JOBS_DB_NAME="plumber"
JOBS_DB_SSLMODE="disable"       # Options: disable, require, verify-ca
JOBS_DB_TIMEZONE="Europe/Paris"

Step 7: (Optional) Add your custom CA

If your GitLab instance (or Plumber with custom certificates) uses a TLS certificate signed by your own Certificate Authority (CA), add the CA certificate file (.pem or .crt) in .docker/ca-certificates/:

cp /path/to/your/ca.pem .docker/ca-certificates/ca.pem

Step 8: Launch the application

docker compose up -d