Skip to content

docker.md

Latest commit

 

History

History
201 lines (142 loc) · 6.49 KB

docker.md

File metadata and controls

201 lines (142 loc) · 6.49 KB

Run GitLab Runner in a container

This is how you can run GitLab Runner inside a Docker container.

General GitLab Runner Docker image usage

GitLab Runner Docker images (both based on Ubuntu and Alpine Linux) are designed as wrappers around the standard gitlab-runner command, like if GitLab Runner was installed directly on the host.

The general rule is that every GitLab Runner command that normally would be executed as:

gitlab-runner [Runner command and options...]

can be executed with:

docker run [chosen docker options...] gitlab/gitlab-runner [Runner command and options...]

For example, getting the top-level help information for GitLab Runner command could be executed as:

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   10.7.0 (7c273476)

(...)

In short, the gitlab-runner part of the command is replaced with docker run [docker options] gitlab/gitlab-runner, while the rest of Runner's command stays as it is described in the register documentation. The only difference is that the gitlab-runner command is executed inside of a Docker container.

Docker image installation and configuration

  1. Install Docker first:

    curl -sSL https://get.docker.com/ | sh

  2. You need to mount a config volume into the gitlab-runner container to be used for configs and other resources:

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

    TIP: Tip: On macOS, use /Users/Shared instead of /srv.

    Or, you can use a config container to mount your custom data volume:

    docker run -d --name gitlab-runner-config \
    -v /etc/gitlab-runner \
    busybox:latest \
    /bin/true

    And then, run the Runner:

    docker run -d --name gitlab-runner --restart always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --volumes-from gitlab-runner-config \
    gitlab/gitlab-runner:latest

  3. Register the Runner

Make sure that you read the FAQ section which describes some of the most common problems with GitLab Runner.

Update

Pull the latest version:

docker pull gitlab/gitlab-runner:latest

Stop and remove the existing container:

docker stop gitlab-runner && docker rm gitlab-runner

Start the container as you did originally:

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

NOTE: Note: You need to use the same method for mounting you data volume as you did originally (-v /srv/gitlab-runner/config:/etc/gitlab-runner or --volumes-from gitlab-runner).

Reading GitLab Runner logs

When GitLab Runner is started as a foreground task (whether it's a locally installed binary or inside of a Docker Container), the logs are printed to the standard output. When GitLab Runner is started as a system service (e.g. with Systemd), the logs are in most cases logged through Syslog or other system logging mechanism.

With GitLab Runner started as a Docker based service, since the gitlab-runner ... command is the main process of the container, the logs can be read using the docker logs command.

For example, if GitLab Runner was started with the following command:

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

you may get the logs with:

docker logs gitlab-runner

where gitlab-runner is the name of the container, set with --name gitlab-runner by the first command.

You may find more information about handling container logs at the Docker documentation page.

Installing trusted SSL server certificates

If your GitLab CI server is using self-signed SSL certificates then you should make sure the GitLab CI server certificate is trusted by the gitlab-runner container for them to be able to talk to each other.

The gitlab/gitlab-runner image is configured to look for the trusted SSL certificates at /etc/gitlab-runner/certs/ca.crt, this can however be changed using the -e "CA_CERTIFICATES_PATH=/DIR/CERT" configuration option.

Copy the ca.crt file into the certs directory on the data volume (or container). The ca.crt file should contain the root certificates of all the servers you want gitlab-runner to trust. The gitlab-runner container will import the ca.crt file on startup so if your container is already running you may need to restart it for the changes to take effect.

Alpine Linux

You can also use alternative Alpine Linux based image with much smaller footprint:

gitlab/gitlab-runner    latest              3e8077e209f5        13 hours ago        304.3 MB
gitlab/gitlab-runner    alpine              7c431ac8f30f        13 hours ago        25.98 MB

Alpine Linux image is designed to use only Docker as the method of spawning runners.

The original gitlab/gitlab-runner:latest is based on Ubuntu 16.04 LTS.

SELinux

Some distributions (CentOS, RedHat, Fedora) use SELinux by default to enhance the security of the underlying system.

The special care must be taken when dealing with such configuration.

  1. If you want to use Docker executor to run builds in containers you need to access the /var/run/docker.sock. However, if you have a SELinux in enforcing mode, you will see the Permission denied when accessing the /var/run/docker.sock. Install the selinux-dockersock and to resolve the issue: https://github.com/dpw/selinux-dockersock.

  2. Make sure that persistent directory is created on host: mkdir -p /srv/gitlab-runner/config.

  3. Run docker with :Z on volumes:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
  gitlab/gitlab-runner:latest

More information about the cause and resolution can be found here: http://www.projectatomic.io/blog/2015/06/using-volumes-with-docker-can-cause-problems-with-selinux/