Docker compose Local

Caution

Only for testing on your local computer

This stack has no TLS and is published on localhost, so it is not suitable for production. For a real install, use Docker Compose or Kubernetes.

💻 Requirements

Besides the GitLab version from the common requirements (ports 80/443 and DNS do not apply to a local install), this method asks little of your machine:

Git
Docker with the Compose plugin >= 2.20.2
OpenSSL (used to generate the secrets)
Port 3000 free
Supported platforms: macOS (bash) and Ubuntu (bash). These are tested and supported.

⚠️ Windows / WSL

Plumber’s install scripts target native Linux and macOS. WSL (Windows Subsystem for Linux) has worked for some users, but we do not officially support it: depending on your WSL setup, how you cloned the repository and your Git settings, you may have to fix the scripts by hand. On a CRLF error (for example bad interpreter: /bin/bash^M, or a stray \r), convert the line endings with dos2unix.

🚀 Installation

The local stack runs the same four components as a production install (backend, frontend, PostgreSQL, Redis) behind a Traefik on plain HTTP, on the single origin (why) http://localhost:3000.

Run the interactive installer:

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

Choose Local. The installer asks for:

your GitLab instance URL
the connection scope: the whole instance, or one root group and its path
the GitLab OAuth application: it prints the link to create it and the exact redirect URI, http://localhost:3000/api/v1/auth/callback, then asks for the Application ID and the Secret

Answer yes to Start Plumber now?, then open http://localhost:3000 and sign in with GitLab as a Plumber Admin to finish the setup.

Info

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

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

Step 1: Create the GitLab application

Create the GitLab OAuth application with the redirect URI http://localhost:3000/api/v1/auth/callback. For a local test, your own Applications page is enough: Your picture > Preferences > Applications (example: gitlab.com).

Keep this GitLab tab open: the Application ID and Secret are used in the bootstrap step.

Step 2: Setup your environment

Clone the repository locally

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

Create your configuration file

cp .env.example .env

Step 3: Update the configuration

Edit .env:

set your GitLab instance URL
.env
```
GITLAB_URL="https://<your-gitlab-url>"
```
delete the DOMAIN_NAME line. The local stack does not use it, and the update script reads its presence to tell a production install from a local one.

Step 4: Generate the secrets

perl -pi -e "s|^PLUMBER_TOKEN_ENCRYPTION_KEY=.*|PLUMBER_TOKEN_ENCRYPTION_KEY=\"$(openssl rand -hex 32)\"|" .env
perl -pi -e "s|^PLUMBER_DB_PASSWORD=.*|PLUMBER_DB_PASSWORD=\"$(openssl rand -hex 16)\"|" .env
perl -pi -e "s|^PLUMBER_REDIS_PASSWORD=.*|PLUMBER_REDIS_PASSWORD=\"$(openssl rand -hex 16)\"|" .env

These commands edit .env in place and leave no backup file behind. PLUMBER_TOKEN_ENCRYPTION_KEY must be exactly 64 hexadecimal characters.

Step 5: Launch Plumber

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

Step 6: Configure the GitLab connection

Run plumber-bootstrap once, inside the backend container. Note the -f compose.local.yml flag: every docker compose command for the local stack needs it.

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

Use -scope group -root-group <path> to connect a single root group.

Open your Plumber test instance at http://localhost:3000 and sign in with GitLab as a Plumber Admin to finish the setup.

⏫ Update

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

./scripts/update.sh

🧹 Remove it

The local stack is disposable. To throw it away, including its data:

docker compose -f compose.local.yml down -v