Skip to main content
On this page

Podman Local

Info

This method is supported by Plumber community.

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 podman on your local computer. This is not suitable for production

💻 Requirements

  • GitLab instance version >=17.7
  • Git
  • podman
  • Docker hub registry must be resolved by podman in file /etc/containers/registries.conf
/etc/containers/registries.conf
unqualified-search-registries = ["docker.io"]

🛠️ Installation

  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 :

    1. Name: Plumber self-managed
    2. Redirect URI : http://localhost:3001/api/auth/gitlab/callback
    3. Confidential: true (let the box checked)
    4. Scopes: api

    Click on Save Application and you should see the following screen: Application

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

  2. 📥 Setup your environment

    Clone the repository locally

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

    Create your configuration file

    Terminal window
    cp .env.local.example .env

  3. 📚 Update the configuration

    Edit the .env file:

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

      .env
      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=""

    Run the following commands to generate random secrets for all components:

    Terminal window
    sed -i "s/REPLACE_ME_BY_SECRET_KEY/$(openssl rand -hex 32)/g" .env
    sed -i "s/REPLACE_ME_BY_JOBS_DB_PASSWORD/$(openssl rand -hex 16)/g" .env
    sed -i "s/REPLACE_ME_BY_JOBS_REDIS_PASSWORD/$(openssl rand -hex 16)/g" .env

  4. 📄 Prepare podman for launch

    Generate podman network:

    Terminal window
    podman network create intranet

    Generate podman socket

    Terminal window
    systemctl --user start podman.socket
    systemctl --user enable podman.socket

    Generate podman config files:

    Terminal window
    set -a; source .env; set +a
    export uid=$(id -u)
    envsubst < podman.local.yml.example > podman.yml
    envsubst < configmap.local.yml.example > configmap.yml

  5. 🚀 Launch Plumber!

    Start Plumber

    Terminal window
    podman play kube podman.yml --configmap configmap.yml --network intranet

    Open your Plumber test instance 👉 click here 🎉

⏫ Update Plumber

Follow these steps to update your self-managed instance to a new version:

  1. Navigate to the location of your platform git repository

  2. Update it

    Terminal window
    git pull

  3. Open the .env.local.example file and copy the values of FRONTEND_IMAGE_TAG and BACKEND_IMAGE_TAG variables

  4. Edit the .env file by updating values of FRONTEND_IMAGE_TAG and BACKEND_IMAGE_TAG variables with the values previously copied

    .env
    FRONTEND_IMAGE_TAG="<new frontend version>"
    BACKEND_IMAGE_TAG="<new backend version>"

  5. Update local yaml files

    Terminal window
    set -a; source .env; set +a
    export uid=$(id -u)
    envsubst < podman.local.yml.example > podman.yml
    envsubst < configmap.local.yml.example > configmap.yml

  6. Restart your containers

    Terminal window
    podman play kube podman.yml --replace --configmap configmap.yml --network intranet

  7. You have successfully updated Plumber on your server 🎉