On this page

Docker compose Local

Caution

Only for testing purposes on your local computer

This page describes how to quickly setup a self-managed instance of Plumber for testing purposes using Docker-compose on your local computer. This is not suitable for production

💻 Requirements

GitLab instance version >=17.7
Git
Docker >= 20.10
Supported platforms: macOS (bash) and Ubuntu (bash). These are tested and supported.

⚠️ Windows / WSL

Plumber’s install scripts are designed for native Linux and macOS environments. 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

Run the interactive installer:

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

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

GitLab OIDC application setup
Secrets: automatically generated

At the end, Plumber will start on http://localhost:3000.

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: Create GitLab Application

On your GitLab instance, open the Applications page: Your picture > Preferences > Applications (example: gitlab.com)

Create an application with the following information:

Name: Plumber
Redirect URI: http://localhost:3001/api/auth/gitlab/callback
Confidential: true (keep the box checked)
Scopes: api

Click on Save Application. Keep this GitLab tab open, the Application ID and Secret will be used in the configuration step.

Step 2: Setup your environment

Clone the repository locally

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

Create your configuration file

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

Step 3: Update the configuration

Edit the .env file:

Copy/paste the Application ID and the Secret from the GitLab application you just created

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

Replace <your-gitlab-url> by domain of your GitLab server
.env
```
JOBS_GITLAB_URL="https://<your-gitlab-url>"
```
If you want to connect Plumber to a specific GitLab group only: add the path of the group in ORGANIZATION variable (to run the onboarding, you must be at least Maintainer in this group)
.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 4: 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 5: Launch Plumber

docker compose -f compose.local.yml up -d

Open your Plumber test instance at http://localhost:3000

⏫ Update

To update your local instance to a new version, run the update script:

./scripts/update.sh

The script will pull the latest changes, load new image versions, and restart the containers.