How to Run GitLab in Rancher June 2017 1

How to Run GitLab in

Rancher
Rancher Labs

WWW.RANCHER.COM 1
 How to Run GitLab in Rancher
Introduction
GitLab is, at its core, a tool
for centrally managing Git
repositories. It provides a robust
authentication and authorization
mechanism, groups, public,
internal, and private repositories,
issue tracking, wiki, snippets, and
everything that one might expect
from a tool that provides this
service.
GitLab goes further by including a
powerful CI engine and a Docker
Container registry, allowing you to go
from development to release inside of
the same utility. It continues by adding
two more powerful OSS utilities:
Prometheus for monitoring and
Mattermost for team communication.
It has a solid API and integrates with
existing third-party systems like JIRA,
Bugzilla, Pivotal, Slack, HipChat,
Bamboo, and more.
WWW.RANCHER.COM
2
All of this begs the question – why use
GitLab instead of using SaaS services
directly? The answer lies in personal
taste. For most people, paying SaaS
providers for the services that they
provide is an excellent solution. You
can focus on building your application
and let them worry about maintaining
the tools. What if you already have
infrastructure with spare capacity?
What if you just want private
repositories without paying for that
privilege? What if you did the math and
determined that you can save money
by hosting it yourself? What if you just
want to own your own data?
Bringing services in-house opens
you up to the risk of spending more
time managing them and getting
them to talk to each other, which is
why GitLab truly shines as an option.
With one click and a few minutes
of configuration, you can be up and
running with a complete solution.
2
 How to Run GitLab in Rancher 3

DEPLOYING GITLAB The Rancher Catalog contains an entry for GitLab CE that will install the latest version. It assumes
that you have a host where you want to directly open 80 and 443 for HTTP/HTTPS and where you’ll
open a port to map to 22 inside of the container.

The catalog item sets the environment variable GITLAB_OMNIBUS_CONFIG with the values you
provide. GitLab then incorporates these values into its configuration when it launches. For a very
basic GitLab deployment the catalog item is sufficient, but in this tutorial, we’d like to show you how
to do a bit more.

We’re going to deploy Gitlab CE, but we’re not going to open any ports. Host ports are expensive, so
we’ll use a load balancer for this later. We’ll configure HTTPS and the Docker Registry and wire it up
for use with Rancher:

1. Create a new stack called gitlab

2. Add a service to the stack called gitlab
• Image: gitlab/gitlab-ce: latest
• Volumes:
o gitlab-etc:/etc/gitlab
o gitlab-opt:/var/opt/gitlab
o gitlab-log:/var/log/gitlab
• Networking
o Set a specific hostname: git
• Health Check
o HTTP: Port 80
o Path: GET / HTTP/1.0
3. Add a sidekick to the service
• Image: tozd/postfix
• Environment
o MY_NETWORKS: 10.42.0.0/16,127.0.0.0/8
o ROOT_ALIAS: you@yourdomain.com
• Volumes:
o postfix-log:/var/log/postfix
o postfix-spool:/var/spool/postfix
• Health Check:
o TCP: Port 25

Before you launch, you have a couple of options for configuring GitLab:
1. Add all GitLab variables to GITLAB_OMNIBUS_CONFIG
2. Set all variables later

For the first time through, I recommend (2). The default gitlab.rb file that GitLab provides is well-
documented, and if you haven’t worked with GitLab before, you will learn a lot about its capabilities
from going through that file. Go ahead and click Launch - Rancher will fetch the images and bring
them up for you.

WWW.RANCHER.COM 3
 How to Run GitLab in Rancher 4

SET UP SSL While Rancher is fetching the images, add a load balancer with HTTPS. To do this, first create the
OFFLOADING LetsEncrypt container, then add it to the load balancer and wait for the certificate to register. Once
that completes, add the configuration for GitLab to the load balancer.

For this example, we’re going to use the domain example.com with the hostnames of “git” for GitLab
and “registry” for the Docker Registry. Make sure that you’ve added the corresponding records to
your DNS zone file and pointed them to the host where the load balancer will be running before
continuing to the next step.

DEPLOYING LETSENCRYPT

1. From the Community Catalog, choose the LetsEncrypt service. Accept the TOS in the first
dropdown, and then set the following options for HTTP validation:
• Your email address: you@yourdomain.com
• Certificate name: gitlab
• Domain names: git.example.com, registry.example.com
• Domain validation method: HTTP
2. Click Launch to launch the container. You now have 120 seconds to complete the next step.

DEPLOYING THE LOAD BALANCER

1. In the gitlab stack, click the dropdown next to Add Service and choose Add Load Balancer.
Give it a name and add the following services selectors. Alternatively, if you already have an
environment-wide load balancer, edit it to add the services below.
• Public / HTTP
o Port: 80
o Path: /.well-known/acme-challenge
o Target: letsencrypt
o Port: 80
2. Click Edit to save your change

Monitor the logs for the LetsEncrypt container and in two minutes you’ll see it report that it has
registered the certificates for the two domains. If you see errors reporting status 403 or 503, check
your load balancer configuration and make sure that it’s set up correctly. The LetsEncrypt container
will restart and continue to try and register the certificates. Once the registration is successful, you’ll
find the certificates in the Rancher UI under the Infrastructure tab.

We’re ready to add SSL support to Gitlab via the load balancer:
1. Edit the load balancer
2. Add the following Service Rules:
• Public / HTTP
o Host: git.example.com
o Port: 80
o Host: gitlab
o Port: 80

WWW.RANCHER.COM 4
 How to Run GitLab in Rancher 5

• Public / HTTPS
o Host: git.example.com
o Port: 443
o Host: gitlab
o Port: 80
• Public / HTTPS
o Host: registry.example.com
o Port: 443
o Host: gitlab
o Port: 80
• Public / TCP
o Port: 2222
o Host: gitlab
o Port: 22
Click Edit to save your changes.

CONFIGURE GITLAB GitLab’s configuration is saved in /etc/gitlab/gitlab.rb within the container. When we launched the
service, we created a Docker volume to store this data persistently. Within Rancher, find your GitLab
container and log into it with Execute Shell. Change to /etc/gitlab and edit gitlab.rb.

There are many variables within gitlab.rb that you can use to adjust how GitLab behaves. Each
section includes a link to GitLab’s documentation that describes what that service does and what
each variable adjusts.

For this tutorial, find and change or uncomment the following variables:

external_url ‘https://git.example.com’
gitlab_rails[‘gitlab_ssh_host’] = ‘git.example.com’
gitlab_rails[‘gitlab_email_enabled’] = true
gitlab_rails[‘gitlab_email_from’] = ‘git@example.com’
gitlab_rails[‘gitlab_email_display_name’] = ‘Gitlab’
gitlab_rails[‘gitlab_email_reply_to’] = ‘noreply@example.com’
gitlab_rails[‘gravatar_plain_url’] = ‘https://secure.gravatar.com/
avatar/%{hash}?s=%{size}&d=identicon’
gitlab_rails[‘gravatar_ssl_url’] = ‘https://secure.gravatar.com/
avatar/%{hash}?s=%{size}&d=identicon’
gitlab_rails[‘gitlab_shell_ssh_port’] = 2222
gitlab_rails[‘smtp_enable’] = true
gitlab_rails[‘smtp_address’] = ‘postfix’
gitlab_rails[‘smtp_port’] = 25
gitlab_rails[‘smtp_domain’] = ‘yourdomain.com’
gitlab_rails[‘smtp_authentication’] = false

WWW.RANCHER.COM 5
 How to Run GitLab in Rancher 6

gitlab_rails[‘smtp_enable_starttls_auto’] = false
gitlab_rails[‘manage_backup_path’] = true
gitlab_rails[‘backup_path’] = ‘/var/opt/gitlab/backups’
gitlab_rails[‘backup_archive_permissions’] = 0644
gitlab_rails[‘backup_pg_schema’] = ‘public’
gitlab_rails[‘backup_keep_time’] = 604800
registry_external_url ‘https://registry.example.com’
gitlab_rails[‘registry_enabled’] = true
gitlab_rails[‘registry_host’] = ‘registry.example.com’
gitlab_rails[‘registry_api_url’] = ‘http://localhost:5000’
gitlab_rails[‘registry_key_path’] = ‘/var/opt/gitlab/gitlab-rails/
certificate.key’
gitlab_rails[‘registry_path’] = ‘/var/opt/gitlab/gitlab-rails/shared/
registry’
gitlab_rails[‘registry_issuer’] = ‘omnibus-gitlab-issuer’
registry[‘enable’] = true
registry[‘token_realm’] = ‘https://git.example.com’
nginx[‘listen_port’] = 80
nginx[‘listen_https’] = false
nginx[‘proxy_set_headers’] = {
‘Host’ => ‘$http_host_with_default’,
‘X-Real-IP’ => ‘$remote_addr’,
‘X-Forwarded-For’ => ‘$proxy_add_x_forwarded_for’,
‘X-Forwarded-Proto’ => ‘https’,
‘X-Forwarded-Ssl’ => ‘on’,
‘Upgrade’ => ‘$http_upgrade’,
‘Connection’ => ‘$connection_upgrade’
}
registry_nginx[‘enable’] = true
registry_nginx[‘listen_port’] = 80
registry_nginx[‘listen_https’] = false
registry_nginx[‘proxy_set_headers’] = {
‘Host’ => ‘$http_host’,
‘X-Real-IP’ => ‘$remote_addr’,
‘X-Forwarded-For’ => ‘$proxy_add_x_forwarded_for’,
‘X-Forwarded-Proto’ => ‘https’,
‘X-Forwarded-Ssl’ => ‘on’
}
registry_nginx[‘custom_gitlab_server_config’] = ‘proxy_cache_convert_head
off;’

WWW.RANCHER.COM 6
 How to Run GitLab in Rancher 7

With these variables changed, you’ll have accomplished the following:

1. Set the hostname for your git URLs
2. Configured GitLab to bounce HTTP to HTTPS
3. Enabled HTTPS gravatar URLs for both HTTP and HTTPS (necessary to avoid mixed-content
errors)
4. Set the reported SSH port to 2222
5. Activated emails from GitLab
6. Enabled email delivery through the Postfix sidekick
7. Activated nightly backups with a one week retention period
8. Enabled the Container Registry
9. Activated the configuration and required headers for GitLab to understand that it’s behind an
SSL load balancer

Save this file, and reconfigure GitLab by typing gitlab-ctl reconfigure and pressing Enter. GitlLab will
rebuild its configuration files and restart services that need to be restarted.

LOGGING IN You’re ready to go! Point your browser at https://git.example.com and you’ll be greeted with a screen
that asks you to set a password. This is for the default user, named root, and once you’ve set the
password, you’ll be asked to log in again.

Congratulations! You have a running GitLab instance! There are still some changes that we need to
make inside of GitLab to secure it, so keep reading.

LOCKING IT DOWN We recommend that you make the following changes:

CHANGE THE ROOT USERNAME

Logging into anything as root is bad, and that username is a known target. You’re logged in as the only
user right now, and the first thing you should do is change your username.

1. Click the wrench icon in the top right, next to the search bar
2. Select Administrator in the bottom of the middle column
3. Select the Edit button in the top right
4. Change your name, username, and email address
5. Scroll down and click Save Changes

The Administrator account’s old email address was admin@example.com, and changing this
information just tried to send an email to that account to inform it of the change.

1. Back in Rancher, find your postfix container and Execute Shell

2. Type mailq and press Enter. You should see a deferred message stuck in the queue. Note its ID.
3. Type postsuper –d <id> and press Enter. This will delete that message from the queue.

WWW.RANCHER.COM 7
 How to Run GitLab in Rancher 8

DISABLE PUBLIC SIGN-UP

This next change will keep the Internet from taking over your new Gitlab instance and using it for
their nefarious ends.

1. Click the wrench icon again to return to the Admin dashboard

2. Click the dropdown next to the gear icon in the top right and choose Settings
3. You can adjust any of these to suit your needs, but the one you want to disable is the default of
Sign-up enabled under Sign-up Restrictions.

CHECK YOUR PORTS

In this example, we’re using ports 80, 443, and 2222. No other ports on the host are necessary for
GitLab, but 2222 is not a common port. Make sure that you have this open in your firewall.

At this point, you have an awesome GitLab installation. You can immediately start using it for your
projects.

ADD YOUR SSH KEY Although you can work with GitLab over HTTP, doing so over SSH is more common. Before you can
do this, you need to add your SSH public key to GitLab so it knows who you are. If you don’t have an
SSH key, you can make one (on Linux or Mac) with:

ssh-keygen -b 2048

Always use a passphrase for security; your key might have permission to log in as a privileged user,
and if your laptop is ever compromised, you don’t want to give an attacker that level of access. (If you
prefer not to use a passphrase or deal with ssh agents, see the excellent Kryptonite project at
https://krypt.co.)

Save this with the defaults (or choose a new key name), and then in GitLab:
• Check the dropdown next to your avatar in the top right corner, and select Settings followed by
SSH Keys
• Paste your public key (the contents of the file tha ends in .pub) into the box on the page that
opens.

USING GITLAB GitLab CI is a powerful tool for continuous integration and continuous delivery. To use it with
MULTI-RUNNER TO Rancher, we’ll deploy a runner that will execute jobs.
BUILD CONTAINERS LAUNCHING THE RUNNER

There are several ways that runners can be deployed, but since we’ll be targeting building containers
from our repositories, we’ll run a Docker container that has direct to /var/run/docker.sock to build
images that are siblings to itself.

WWW.RANCHER.COM 8
 How to Run GitLab in Rancher 9

1. In Rancher, add a service to your GitLab stack

2. Set it up with the following configuration:
• Name: runner01
• Image: gitlab/gitlab-runner
• Console: None
• Volume:
o /var/run/docker.sock:/var/run/docker.sock
o runner01-etc:/etc/gitlab-runner

When the container launches, it will create a default configuration in /etc/gitlab-runner, to which
we’ve connected a volume. The next step is to register the runner with your Gitlab instance.

The options that I’m setting below are correct for a basic runner that will build any job. You can also
limit runners to specific repositories or use other images. Read the documentation from Gitlab to
learn what options are best for your environment.

CONFIGURING THE RUNNER

1. Execute a shell into the container
2. Run gitlab-ci-multi-runner register to begin the registration process
3. Answer the questions that it asks according to the following example (answers are in bold):

root@4bd974b1c799:/# gitlab-ci-multi-runner register

Running in system-mode.

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):

https://git.example.com
Please enter the gitlab-ci token for this runner:
DGQ-J7n0tR33LXB3z_
Please enter the gitlab-ci description for this runner:
[4bd974b1c799]: runner01
Please enter the gitlab-ci tags for this runner (comma separated):
<press enter>
Whether to lock Runner to current project [true/false]:
[false]: <press enter>
Registering runner... succeeded runner=DGQ-J7dD
Please enter the executor: docker, parallels, ssh, docker-ssh+machine,
kubernetes, docker-ssh, shell, virtualbox, docker+machine:
docker
Please enter the default Docker image (e.g. ruby:2.1):
docker:stable
Runner registered successfully. Feel free to start it, but if it’s running
already the config should be automatically reloaded!

WWW.RANCHER.COM 9
 How to Run GitLab in Rancher 10

The main items to note are:

• Enter the URL for your GitLab instance
• Enter the runner token (found in Admin/Runners)
• Give your runner a recognizable name
• Choose runner type of docker
• Choose the docker:stable container image

After the initial registration completes, we need to edit the /etc/gitlab-runner/config.toml and make a
change:
• volumes = [“/var/run/docker.sock:/var/run/docker.sock”, “/cache”]

This will mount /var/run/docker.sock inside the container so that containers that it builds will be stored
in the images store of the host itself. This is a far better solution than Docker in Docker.

Changes to config.toml are picked up automatically by the runner, so you don’t need to restart. You
can see and interact with your runner in Gitlab under Admin/Runners.

CONFIGURING A GitLab’s Container Registry is tied directly to repositories, so you won’t be able to push containers

PROJECT TO USE to arbitrary locations. If you have a repository called demo-php in group docker, the path to the image
will be registry.example.com/docker/demo-php with tags defined according to how you tell GitLab CI to
GITLAB’S CONTAINER
build the containers.
REGISTRY
For the rest of this example, I’ll use the repository whose content you can find at https://github.com/
oskapt/rancher-GitLab-demo. To set this up in your GitLab environment:

1. Create a project in GitLab. In this tutorial, we’ll call it example/demo (the group is example, and
the project is demo)
2. Clone and modify the rancher-gitlab-demo repo

$ git clone https://github.com/oskapt/rancher-gitlab-demo.git demo

$ cd demo
$ git remote set-url origin ssh://git@git.example.com:2222/example/demo.git
$ git push -u origin master

What we’ve just done is cloned the source repo, changed the target URL for origin, and pushed the
repo to our GitLab instance. Because there are no CI instructions yet, GitLab won’t build anything.

The repository contains a file named .gitlab-ci.yml.sample that contains our CI instructions. Let’s
create a branch for development and then rename this file so that we can edit it:

$ git checkout -b develop

$ git mv .gitlab-ci.yml.sample .gitlab-ci.yml

WWW.RANCHER.COM 10
 How to Run GitLab in Rancher 11

The file looks like this:

variables:
REGISTRY_HOST: registry.example.com
TEST_IMAGE: $REGISTRY_HOST/$CI_PROJECT_PATH:$CI_BUILD_REF_NAME
RELEASE_IMAGE: $REGISTRY_HOST/$CI_PROJECT_PATH:latest

stages:
- build
- release

before_script:
- docker info
- docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN $REGISTRY_HOST

build:
stage: build
script:
- docker build --pull -t $TEST_IMAGE .
- docker push $TEST_IMAGE

release:
stage: release
script:
- docker pull $TEST_IMAGE
- docker tag $TEST_IMAGE $RELEASE_IMAGE
- docker push $RELEASE_IMAGE
only:
- master

push_to_docker_hub:
# in order for this to work you will need to set
# `HUB_USERNAME` and `HUB_PASSWORD` as CI variables
# in the Gitlab project
stage: release
variables:
DOCKER_IMAGE: $HUB_USERNAME/$CI_PROJECT_NAME:latest
script:
- docker login -u $HUB_USERNAME -p $HUB_PASSWORD
- docker tag $RELEASE_IMAGE $DOCKER_IMAGE
- docker push $DOCKER_IMAGE
only:
- master
when: manual

WWW.RANCHER.COM 11
 How to Run GitLab in Rancher 12

We’ve designed this CI file to be used in multiple basic Docker projects without any modification.
After you set the items in the variables section to your liking, the rest of the file will adapt to any
project.

There are two stages: build and release. GitLab has its own token that allows it to log into its own
registry, which it does in the before_script section. It then executes the script commands in the build
section, which will build your container and tag it with the format designated in the TEST_IMAGE
variable. The result will be a container tagged with the branch name, like this for our develop branch:

registry.example.com/example/demo:develop

It then pushes this into the registry.

If you push to the master branch, it does all of this and then continues with the release stage to tag the
image with latest before pushing it. The result is a container tagged both master and latest, and since
latest is the default tag name, you can pull it without specifying the tag at all.

Finally, a manual option available for the master branch is to push the container to Docker Hub. For
this to work you have to first set HUB_USERNAME and HUB_PASSWORD in the GitLab project
under Settings | CI/CD Pipelines | Secret Variables. Gitlab CI will re-tag the master image with the value
of DOCKER_IMAGE and then push it out to Docker Hub. Because we’ve specified manual for when,
GitLab will not do this automatically. You’ll have to manually execute this stage from GitLab.

BUILDING A Commit these changes and push them to your GitLab project in the develop branch. If everything has
CONTAINER VIA been set up correctly, you’ll be able to see the pipeline start under the Pipelines tab in the project. You

GITLAB CI can select the Status icon to view a detailed progress log for the stages.

If there are any issues, GitLab CI will report that the pipeline failed, and you can view the log to see
why. When you fix the issues and push a new commit, it will start a new pipeline. If the error was
transient (unable to connect to Docker Hub, for example), you can run that stage of the pipeline
again.

If you ever want to just run a pipeline from the existing code, you can do so by clicking Run Pipeline
and choosing the branch you want to build.

When everything is finished, your pipeline will say Passed and you’ll see your container under the
Registry tab in your GitLab project.

CREATE A Before you can use the registry, you’ll need to add it to Rancher. Rather than use your administrator
DEPLOYMENT USER account, we recommend that you create a deploy user with Reporter permissions on any project you
want to deploy (or any group containing multiple projects).

WWW.RANCHER.COM 12
 How to Run GitLab in Rancher 13

1. Click the wrench in the top right corner to enter the admin area
2. Click the New User button in the bottom of the middle column
3. Create a user named deploy
4. Under Access indicate that the user is External. This will give it restricted access within GitLab.
5. Click Create User, which will take you to a summary screen.

GitLab defaults to sending a login email to the user, so we need to edit the user to set a password:

1. From the summary screen, click Edit in the top right

2. Set a password for the user and click Save Changes
3. Navigate to your project in GitLab and click Settings and then Members
4. Type deploy in the search bar and choose the deploy user
5. Give the user Reporter permissions
6. Click Add to project to save your changes.

The deploy user now has permission to access containers from your project’s container registry.

DEPLOY THE All this setup has brought us to this point - pulling containers from your own private registry and

CONTAINER TO deploying them in Rancher. The last thing we need to do is add the registry and then make a new
stack and service.
RANCHER
1. In Rancher, click Infrastructure and choose Registries
2. Click Add Registry
3. Choose Custom
4. Enter your registry URL (e.g. registry.example.com)
5. Enter your deployment user’s username and password
6. Click Create

With the registry added to Rancher, you’re ready to create services from those images.

1. Create a stack called demo

2. Add a service and name it anything you like. Set the image to use the develop tag of your new
container image.
• registry.example.com/example/demo:develop
3. Click Create

Congratulations! You’ve just deployed the development version of your project from your private
container registry!

WWW.RANCHER.COM 13
 How to Run GitLab in Rancher 14

This has been a long journey, but with all of the heavy lifting done, you can get back to work using the
tools we’ve installed. Some things to do from here:

• Set up groups for your other projects. Use logical collections, like docker or websites for the
projects that will be contained within.
• Import other projects into GitLab
• Set up GitLab CI to build the containers
• Change to the master branch and merge develop to bring in .gitlab-ci.yml and then push that to
GitLab. Update Rancher to pull the latest image tag.
• Add HUB_USERNAME and HUB_PASSWORD to the project, and then manually push your
image to Docker Hub

Have fun!

Rancher and the cow logo are registered trademarks or trademarks of Rancher Labs, Inc. in the United States and other countries.  Other brand names mentioned herein are for identification purpos-
es only and may be trademarks of their respective holder(s).  © 2017 Rancher Labs, Inc. All rights reserved.

WWW.RANCHER.COM