Use Podman to Setup and Manage a GitLab Self-Hosted Instance

Caption: image of the Podman and GitLab Logos

Note: This guide uses the versions of the following applications:

GitLab Community Edition (CE) v18.7.1 in an Ubuntu container on version 24.04 — shown here

GitLab Runner v18.7.2, also in an Ubuntu container on version 24.04 — linked here

Podman version 5.52 running in Windows 11 via Windows Subsystem for Linux (WSL 2)

Second Note: For help setting up WSL 2 and/or Podman in Windows 11, you can follow my step-by-step guide here.

Third Note: These steps are basically interchangeable with Docker if your setup uses Docker Desktop instead of Podman

# For instance, instead of using
podman pull gitlab/gitlab-ce:latest

# With Docker, you can run this
docker pull gitlab/gitlab-ce:latest

Fourth Note: The Enterprise Edition (EE) of GitLab is interchangeable and can be used with this guide in place of the CE.

Initial Setup of Environment

There are some initial steps that you want to follow before creating the container in Podman.

1. Create the persistent volumes that you will need for GitLab CE and the accompanying GitLab Runner containers

# You can create these directories anywhere, just make sure to update the
# volume path in the Podman pull step of this guide

mkdir -p /opt/gitlab-ce/{config,logs,data}

mkdir /opt/gitlab-runner/config

2. Create the network that will connect the GitLab CE instance and the GitLab Runner together (else, GitLab will think it is communicating with itself instead of the Runner, and vice-versa)

podman network create gitlabnet

Additional Help: If you have already created the containers and don’t want to rm and then run them again, you can simply run the following commands to connect the new network to the containers — Otherwise SKIP this portion of the step!

podman network connect --alias gitlab.home gitlabnet <gitlab-container-name>

podman network connect gitlabnet gitlab-runner

3. Update the hosts files for GitLab, so that local DNS will point to the instance correctly.

• In the Podman server, open the hosts file (/etc/hosts) in a text editor and type in the following:

127.0.0.1    gitlab.home

• Repeat this for Windows (hosts file is located in C:\Windows\System32\drivers\etc\hosts).

Initial Setup of GitLab CE and GitLab Runner Containers

1. Pull the version (image) of the gitlab-ce and gitlab-runner containers that you want to run (warning: using the “latest” tags might not align with the remaining steps, depending on the newest version (again, this guide is using GitLab v18.7.x):

podman pull gitlab/gitlab-ce:v18.7.1-ce.0

podman pull gitlab/gitlab-runner:v18.7.2

2. Run (create) the GitLab CE and GitLab Runner containers in detached mode via the following commands:

# Grab the subnet for the gitlabnet network
podman network inspect gitlabnet --format '{{range .Subnets}}{{.Subnet}}{{end}}'

# For GitLab CE
# Note, if above command returns 10.88.0.1/24 for instance, then set a
# an IP address for GitLab in that IP range
podman run -d --name gitlab \
--restart=always \
--hostname gitlab.home \
--network gitlabnet:alias=gitlab.home \
--ip 10.88.0.3 \
-p 8443:443 -p 8080:80 -p 2222:22 \
-v /opt/gitlab/config:/etc/gitlab:Z \
-v /opt/gitlab/logs:/var/log/gitlab:Z \
-v /opt/gitlab/data:/var/opt/gitlab:Z \
gitlab-ce:v18.7.1-ce.0

# For the GitLab Runner
podman run -d --name gitlab-runner \
--restart=always \
--network gitlabnet \
-v /opt/gitlab-runner/config:/etc/gitlab-runner:Z \
gitlab-runner:v18.7.2

After this step, you should be able to access the GitLab GUI in your web browser by navigating to the following:

http://gitlab.home:8080/

Additional GitLab Steps

The remaining steps will include basic account setup and connecting the GitLab Runner to the GitLab CE server. This guide does not go over builds (using a Dockerfile/Containerfile) or any additional config setup. You can read more from the official documentation below:

• Install Docker in a Docker container
• Run GitLab Runner in a container

1. Setup GitLab Accounts

Root user — the root user’s password is a randomized string that is created when the container is first ran. The file lasts for 24 hours and can be located in its temporary folder, either in /opt/gitlab-ce/config on the Podman server or in /etc/gitlab on the container. The name of the file is “initial_root_password”.

2. Remove email confirmation (if not setting up SMTP) for account sign-up:

• Sign into gitlab.home:8080 as the “root” user. After logging in, click on the “Admin” button in the top-right corner of the page.

Caption: Image depicting the location of the “Admin” button, highlighted in yellow.

• Navigate to Settings > General. Click on the dropdown next to Sign-up restrictions, and under “Email confirmation settings” you will want to select the Off radio button. Then make sure to press the “Save changes” button.

This will allow accounts to be created without requiring email confirmation.

Note: Alternatively, you can leave this setting on, create a new user, and on the Podman server run the following command:

podman exec -it gitlab gitlab-rake "gitlab:password:reset"

Type in the username, new password, and confirm new password. This should allow you log into that account without the need for an email confirmation.

3. To register the GitLab Runner, in the Admin panel you will select CI/CD > Runners. Click on the hamburger menu next to the “Create instance runner” button and temporarily copy the Registration token into a notepad.

Back on the Podman server, run the following command:

podman exec -it gitlab-runner vi /etc/hosts

You will need to add the IP address of GitLab CE that was set when first initializing the container in Podman (i.e. 10.88.0.3 gitlab.home). Save this file, and then run this next command below:

podman exec -it gitlab-runner gitlab-runner register

This will start a prompt that asks some questions regarding the Runner (not in this particular order):

# URL of the GitLab instance
http://gitlab.home:8080

# Tag name, which is essentially the name of the runner
# Used to tag the Runner in the pipeline
local-instance-runner

# Description of the runner
Local GitLab instance Runner

# and Registration token which was copied from the GitLab GUI
<registration-token>

You will receive a prompt in the CLI that the Runner has been successfully registered. You can also check this by going back to the Admin area, click on CI/CD > Runners and see an “Online” status next to the Runner.

Caption: Image of GitLab GUI showing a newly registered Runner with “Online” status

You should now have a basic setup of GitLab CE, perfect to begin testing in a lab!