Gitlab - Registry Setup

A Registry is the source of truth for any container image you use. It's a secure way to store and fetch the images you need. To simplify it even further, think of it as a warehouse for container images. Let’s set it up and give it a run. Before we start setting up the Registry VM, we need to tweak some settings on the GitLab Server VM. Step 1 : Configure Gitlab Server VM Edit /etc/gitlab/gitlab.rb with the registry details: ################################################################################ ## Container Registry settings ##! Docs: https://docs.gitlab.com/ee/administration/packages/container_registry.html ################################################################################ registry_external_url 'http://:80' ### Settings used by GitLab application gitlab_rails['registry_enabled'] = true gitlab_rails['registry_host'] = "http://:80" gitlab_rails['registry_port'] = "80" gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry" ###! Notification secret, it's used to authenticate notification requests to GitLab application ###! You only need to change this when you use external Registry service, otherwise ###! it will be taken directly from notification settings of your Registry # gitlab_rails['registry_notification_secret'] = nil ###! Do not change the following 3 settings unless you know what you are ###! doing gitlab_rails['registry_api_url'] = "http://:80" gitlab_rails['registry_key_path'] = "/var/opt/gitlab/gitlab-rails/certificate.key" gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" This generates the certificate.key, which will come in handy later. Now, let's move on to the Registry VM Step 2 : Setup Docker Dependencies yum install containerd.io docker-ce-cli docker-ce systemctl daemon-reload systemctl enable --now docker Step 3 : Create Registry Configuration Directories We’ll store our Registry configs in /etc/docker/registry. mkdir -p /etc/docker/registry chmod 700 /etc/docker/registry This will include: gitlab-registry.crt config.yml. Generate gitlab-registry.crt on the Gitlab Server like this: openssl req -key /var/opt/gitlab/gitlab-rails/certificate.key \ -new -x509 \ -out gitlab-registry.crt \ -subj "/CN=omnibus-gitlab-issuer" Here’s a basic config.yml template you can customize: version: 0.1 log: fields: service: registry level: info storage: cache: blobdescriptor: inmemory filesystem: rootdirectory: /var/lib/registry delete: enabled: true http: addr: 0.0.0.0:80 headers: X-Content-Type-Options: [nosniff] health: storagedriver: enabled: true interval: 10s threshold: 3 auth: token: realm: https://:80/jwt/auth service: container_registry issuer: omnibus-gitlab-issuer rootcertbundle: /etc/docker/registry/gitlab-registry.crt Add the config files: vi gitlab-registry.crt chmod 600 gitlab-registry.crt vi config.yml chmod 600 config.yml Step 4 : Pull the GitLab Container Registry Image. I have Gitlab v17.10.4 setup. Check for your registry version here. docker pull registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v4.15.2-gitlab Step 5 : Run the Registry Image docker run --user root -d --name registry --restart=always -v /etc/docker/registry:/etc/docker/registry -p 80:5000 registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v4.15.2-gitlab Before you go to Gitlab and test it out, the runner will need a slight tweak - Step 6 : Configure Gitlab Runner VM Make sure to add an insecure registry entry in the Gitlab Runner VM /etc/docker/daemon.json as shown below. { "insecure-registries" : [ ":5000" ] } Restart Daemon & Docker Services systemctl daemon-reload systemctl restart docker Finally, run a quick docker login using your GitLab credentials to confirm everything’s wired up correctly. docker login :80 And that's it! You’ve now got a fully functioning private container registry as part of your DevOps setup. In case you got stuck somewhere, feel free to drop a comment — I’ll try to answer as best as I can. You can also checkout gitlab forum for any additional help or queries.

Apr 23, 2025 - 16:12

A Registry is the source of truth for any container image you use. It's a secure way to store and fetch the images you need.

To simplify it even further, think of it as a warehouse for container images. Let’s set it up and give it a run.

Before we start setting up the Registry VM, we need to tweak some settings on the GitLab Server VM.

Step 1 : Configure Gitlab Server VM

Edit /etc/gitlab/gitlab.rb with the registry details:

################################################################################
## Container Registry settings
##! Docs: https://docs.gitlab.com/ee/administration/packages/container_registry.html
################################################################################

registry_external_url 'http://:80'

### Settings used by GitLab application
gitlab_rails['registry_enabled'] = true
gitlab_rails['registry_host'] = "http://:80"
gitlab_rails['registry_port'] = "80"
gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry"

###! Notification secret, it's used to authenticate notification requests to GitLab application
###! You only need to change this when you use external Registry service, otherwise
###! it will be taken directly from notification settings of your Registry
# gitlab_rails['registry_notification_secret'] = nil

###! **Do not change the following 3 settings unless you know what you are
###!   doing**
gitlab_rails['registry_api_url'] = "http://:80"
gitlab_rails['registry_key_path'] = "/var/opt/gitlab/gitlab-rails/certificate.key"
gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer"

This generates the certificate.key, which will come in handy later. Now, let's move on to the Registry VM

Step 2 : Setup Docker Dependencies

yum install containerd.io docker-ce-cli docker-ce
systemctl daemon-reload
systemctl enable --now docker

Step 3 : Create Registry Configuration Directories

We’ll store our Registry configs in /etc/docker/registry.

mkdir -p /etc/docker/registry
chmod 700 /etc/docker/registry

This will include:

gitlab-registry.crt
config.yml.

Generate gitlab-registry.crt on the Gitlab Server like this:

openssl req -key /var/opt/gitlab/gitlab-rails/certificate.key \
            -new -x509 \
            -out gitlab-registry.crt \
            -subj "/CN=omnibus-gitlab-issuer"

Here’s a basic config.yml template you can customize:

version: 0.1
log:
  fields:
    service: registry
  level: info
storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true
http:
  addr: 0.0.0.0:80
  headers:
    X-Content-Type-Options: [nosniff]
health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3
auth:
  token:
    realm: https://:80/jwt/auth
    service: container_registry
    issuer: omnibus-gitlab-issuer
    rootcertbundle: /etc/docker/registry/gitlab-registry.crt

Add the config files:

vi gitlab-registry.crt
chmod 600 gitlab-registry.crt
vi config.yml
chmod 600 config.yml

Step 4 : Pull the GitLab Container Registry Image.

I have Gitlab v17.10.4 setup. Check for your registry version here.

docker pull registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v4.15.2-gitlab

Step 5 : Run the Registry Image

docker run --user root -d --name registry --restart=always -v /etc/docker/registry:/etc/docker/registry -p 80:5000 registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v4.15.2-gitlab

Before you go to Gitlab and test it out, the runner will need a slight tweak -

Step 6 : Configure Gitlab Runner VM

Make sure to add an insecure registry entry in the Gitlab Runner VM /etc/docker/daemon.json as shown below.

{
    "insecure-registries" : [ ":5000" ]
}

Restart Daemon & Docker Services

systemctl daemon-reload
systemctl restart docker

Finally, run a quick docker login using your GitLab credentials to confirm everything’s wired up correctly.

docker login :80

And that's it! You’ve now got a fully functioning private container registry as part of your DevOps setup.

In case you got stuck somewhere, feel free to drop a comment — I’ll try to answer as best as I can.

You can also checkout gitlab forum for any additional help or queries.