Integrating a Project with GitLab

Introduction

GitLab is a DevOps platform that enables users to perform tasks in a project - from project planning and source code management to monitoring and security. GitLab also provides free open & private repositories, issue-following capabilities, and wikis.

Setting Up A Self-Hosted Instance of GitLab

Required Docker Images

Pull the following Docker images from GitLab's public Docker registry:

gitlab/gitlab-ee:latest
gitlab/gitlab-runner

Set Up The Volumes Location

Configure a new environment variable $GITLAB_HOME pointing to the directory where the configuration, logs, and data files will reside. The directory the environment variable is pointing to must already exist since it will not be automatically created.

An example of a path to point the environment variable to is /srv/gitlab:

mkdir /srv/gitlab
export GITLAB_HOME=/srv/gitlab

The GitLab container uses host mounted volumes to store persistent data:

Local Location	Container Location	Usage
`$GITLAB_HOME/data`	`/var/opt/gitlab`	For storing application data.
`$GITLAB_HOME/logs`	`/var/opt/gitlab`	For storing logs.
`$GITLAB_HOME/config`	`/etc/gitlab`	For storing the GitLab configuration files.

Installing Self-Hosted GitLab Instance

By default, GitLab will run on port 80. If port 80 has already been allocated, refer to the section Additional GitLab Configurations. Once the GITLAB_HOME variable has been set, run the image with the following command:

sudo docker run --detach \
  --hostname [INSERT DOMAIN NAME OR IP ADDRESS] \
  --publish 80:80 \
  --name gitlab \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab \
  --volume $GITLAB_HOME/logs:/var/log/gitlab \
  --volume $GITLAB_HOME/data:/var/opt/gitlab \
  gitlab/gitlab-ee:latest

The initialization process may take a long time. If this is the case, track this process with the following command:

sudo docker logs -f gitlab

After starting a container, visit the inputted domain name or IP address (ex: http://example.com or http://[IP-ADDRESS]) with the published port. It might take a while before the Docker container starts to respond to queries.

Visit the GitLab URL, and log in with username root and the password from the following command:

sudo docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

The password file will automatically be deleted in the first reconfigure run after 24 hours.

Configuration

Browsing GitLab Docker Container's Configuration Files

This container uses the official Omnibus GitLab package, so all configuration is done in the unique configuration file /etc/gitlab/gitlab.rb.
To access the GitLab configuration file, start a shell session in the context of a running container. This allows for the ability to browse all directories and to use a preferred text editor:

sudo docker exec -it gitlab /bin/bash

Editing GitLab Docker Container's Configuration Files

Another option is to just edit /etc/gitlaab/gitlab.rb:

sudo docker exec -it gitlab editor /etc/gitlab/gitlab.rb

After opening /etc/gitlab/gitlab.rb, set the external_url to point to a valid URL if the change is desired:

external_url "http://domainname.com"

After making the desired changes, restart the container in order to reconfigure GitLab:

sudo docker restart gitlab

GitLab will reconfigure itself whenever the container starts.

GitLab Runner

Prerequisites:

Docker
docker:latest Docker image

According to the GitLab documentation, the GitLab Runner should be installed on a machine that is separate from the one that runs the self-hosted GitLab instance. The machine needs to be able to communicate and send requests to the machine running the self-hosted GitLab instance. Similarly, the machine running the self-hosted GitLab instance needs to be able to communicate and respond to the requests made by the other machine.

Installing and Registering GitLab Runner

First, open up a browser, navigate to the domain name or IP address that was defined as the hostname when installing GitLab and log into GitLab. Navigate to an existing repository, or create a new repository.

In a repository, navigate to Settings in the sidebar and click CI/CD. Expand the Runners section and save the URL and Registration Token for later use.

Navigate to the separate machine in which the GitLab Runner will be registered. Make sure the GitLab Runner docker image from gitlab-docker-images.tar has been loaded into Docker for this machine.

Run the following command to register the runner:

sudo docker run --rm -it -v /etc/gitlab-runner:/etc/gitlab-runner gitlab/gitlab-runner register

When prompted, input the URL of the self-hosted GitLab instance and the token, which were taken earlier from the Runners page.
Add in a description for the Runner and some tags (ex: develop, production, etc.)
For the executor, enter docker and for the default Docker image, use docker:latest.

Make the following changes to /etc/gitlab-runner/config.toml:
- Add Docker socket to volumes: volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
- Add pull_policy = "if-not-present" to the executor configuration

Start the runner with the following command:

sudo docker run -d --restart always --name gitlab-runner -v /etc/gitlab-runner:/etc/gitlab-runner -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest

Navigate back to the GitLab repository. Go to Settings -> CI/CD. Expand the Runners section and the new runner can be found under Available specific runners.

Using GitLab CI/CD

GitLab CI/CD is a tool for software development using the continuous methodologies:

Continuous Integration (CI)
Continuous Delivery (CD)
Continuous Deployment (CD)

GitLab CI/CD helps users catch bugs and errors early in the development cycle.
To get started, the GitLab Documentation offers a guide on how to use the tool.

Additional GitLab Configurations

The official GitLab Documentation offers additional configuration options for users in the event that the earlier suggested configuration does not fit the user's needs.

Troubleshooting

The official GitLab Documentation offers suggestions to assist users encountering problems using Gitlab and Docker.