Docker compose

Caution

This page documents the v1 line of the Plumber Platform (repository github.com/getplumber/platform), kept here for existing installations. New installations use v2: see the current installation documentation. v1 and v2 are not compatible, they do not share a database, and there is no automated migration.

This page describes how to set up a self-managed instance of Plumber using Docker-compose.

💻 Requirements

GitLab instance version >=17.7
The system requires a Linux server. It runs in 🐳 Docker containers using a docker-compose configuration. Specifications:
- OS: Ubuntu or Debian (tested and supported)
- Hardware
  - CPU x86_64/amd64 with at least 2 cores
  - 4 GB RAM
  - 100 GB of storage for Plumber
- Network
  - Users must be able to reach the Plumber server on TCP ports 80 and 443
  - The Plumber server must be able to access internet
  - The Plumber server must be able to communicate with GitLab instance
  - The installation process requires write access to the DNS Zone to set up Plumber domain
- Installed software
  - Git
  - Docker >= 20.10

⚠️ Windows / WSL

Plumber’s install scripts are designed for native Linux environments (Ubuntu, Debian). Some users have successfully installed Plumber through WSL (Windows Subsystem for Linux), but we do not officially support this setup. Depending on your WSL configuration, how you cloned the repository, and your Git settings, you may need to adjust script files manually. If you see CRLF-related errors (for example bad interpreter: /bin/bash^M), or \r convert line endings with dos2unix.

🚀 Installation

1. Configure your DNS

Create a DNS A record pointing your chosen domain to your server’s public IP address:

Name: <your_plumber_domain> (e.g. plumber.mydomain.com)
Type: A
Content: <your-server-public-ip>

2. Setup Plumber

Run the interactive installer on your server:

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

Choose option 1 (Production): type 1 and press Enter. The installer will guide you through:

Domain name configuration
GitLab OIDC application setup
TLS certificate method selection
Database: internal PostgreSQL or your own external database
Secrets: automatically generated

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

Info

You can also clone the repository first and run the installer locally:

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.
.env
```
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)
.env
```
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:

Name: Plumber
Redirect URI: https://<your_plumber_domain>/api/auth/gitlab/callback
Confidential: true (keep the box checked)
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:

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

These commands edit .env in place and leave no backup file behind.

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:
.env
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

⏫ Update

To update your self-managed instance to a new version, run the update script:

./scripts/update.sh

The script will:

Stop the running containers
Pull the latest changes from the git repository
Load the new image versions
Migrate your .env configuration if needed
Start the containers with the new images

🔄 Backup and restore

Data required to fully backup and restore a Plumber system are the following:

Configuration file: .env
Databases:
- PostgreSQL database of Jobs service
Files data:
- File storing data about certificate for Traefik service

All these data can be easily backup and restored using 2 scripts from the installation git repository:

scripts/backup.sh
scripts/restore.sh

💽 Backup

To backup the system, go to your installation git repository and run the following command:

./scripts/backup.sh 18

The script will create a backups directory and create a backup archive inside it prefixed with the date (backup_plumber-$DATE)

Info

You can use a cron job to perform regular backups. Here is a cron job that launch a backup every day at 2am:

0 2 * * * /plumber-platform/scripts/backup.sh 18

It can be added to your crontab with the command crontab -e. Check more information about cron jobs here.

🛳️ Restore

To restore a backup from scratch on a new system, follow this process:

Be sure that your new system is compliant with requirements
Copy the backup file on your new server

Clone the installation repository

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

If the IP address of your server changed from your previous installation, update your DNS records. See Configure your DNS
Start the stack
Terminal window
```
docker compose up -d
```
The restore script runs pg_restore in a container on the stack’s network, against the running postgres service.

Launch the restore script

./scripts/restore.sh 18 <path_to_your_backup_file>