Configure Gitlab Runner Docker

GitLab CI/CD allows you to use Docker Engine to build and test Docker-based projects.

One of the new trends in Continuous Integration/Deployment is to:

GitLab Community Edition. Skip to content. Projects Groups Snippets Help. General GitLab Runner Docker image usage. GitLab Runner Docker images (based on Ubuntu or Alpine Linux)are designed as wrappers around the standard gitlab-runner command, like ifGitLab Runner was installed directly on the host. The general rule is that every GitLab Runner command that normally would be executedas: can be executed with.

1. Create an application image.
2. Run tests against the created image.
3. Push image to a remote registry.
4. Deploy to a server from the pushed image.

It's also useful when your application already has the Dockerfile that can beused to create and test an image:

This requires special configuration of GitLab Runner to enable docker supportduring jobs.

Runner Configuration

There are three methods to enable the use of docker build and docker runduring jobs, each with their own tradeoffs.

An alternative to using docker build is to use kaniko.This avoids having to execute a runner in privileged mode.

TIP: Tip:To see how Docker and GitLab Runner are configured for shared runners onGitLab.com, see GitLab.com sharedrunners.

Use shell executor

The simplest approach is to install GitLab Runner in shell execution mode.GitLab Runner then executes job scripts as the gitlab-runner user.

1. Install GitLab Runner.

2. During GitLab Runner installation select shell as method of executing job scripts or use command:

3. Install Docker Engine on server.

   For more information how to install Docker Engine on different systems,check out the Supported installations.

4. Add gitlab-runner user to docker group:

5. Verify that gitlab-runner has access to Docker:

   You can now verify that everything works by adding docker info to .gitlab-ci.yml:

6. You can now use docker command (and installdocker-compose if needed).

NOTE: Note:By adding gitlab-runner to the docker group you are effectively granting gitlab-runner full root permissions.For more information please read On Docker security: docker group considered harmful.

Use Docker-in-Docker workflow with Docker executor

The second approach is to use the special Docker-in-Docker (dind)Docker image with all tools installed(docker) and run the job script in context of thatimage in privileged mode.

NOTE: Note:docker-compose is not part of Docker-in-Docker (dind). To use docker-compose in yourCI builds, follow the docker-composeinstallation instructions.

DANGER: Danger:By enabling --docker-privileged, you are effectively disabling all ofthe security mechanisms of containers and exposing your host to privilegeescalation which can lead to container breakout. For more information, checkout the official Docker documentation onRuntime privilege and Linux capabilities.

Docker-in-Docker works well, and is the recommended configuration, but it isnot without its own challenges:

• When using Docker-in-Docker, each job is in a clean environment without the pasthistory. Concurrent jobs work fine because every build gets its owninstance of Docker engine so they don't conflict with each other. But thisalso means that jobs can be slower because there's no caching of layers.

• By default, Docker 17.09 and higher uses --storage-driver overlay2 which isthe recommended storage driver. See Using the overlayfs driverfor details.

• Since the docker:19.03.12-dind container and the runner container don't share theirroot file system, the job's working directory can be used as a mount point forchild containers. For example, if you have files you want to share with achild container, you may create a subdirectory under /builds/$CI_PROJECT_PATHand use it as your mount point (for a more thorough explanation, check issue#41227):

An example project using this approach can be found here: https://gitlab.com/gitlab-examples/docker.

In the examples below, we are using Docker images tags to specify aspecific version, such as docker:19.03.12. If tags like docker:stableare used, you have no control over what version is used. This can lead tounpredictable behavior, especially when new versions arereleased.

TLS enabled

NOTE: Note:Requires GitLab Runner 11.11 or later, but is not supported if GitLabRunner is installed using the Helmchart. See therelatedissue fordetails.

The Docker daemon supports connection over TLS and it's done by defaultfor Docker 19.03.12 or higher. This is the suggested way to use theDocker-in-Docker service andGitLab.com shared runnerssupport this.

1. Install GitLab Runner.

2. Register GitLab Runner from the command line to use docker and privilegedmode:

   The above command registers a new runner to use the specialdocker:19.03.12 image, which is provided by Docker. Notice that it'susing the privileged mode to start the build and servicecontainers. If you want to use Docker-in-Docker mode, you alwayshave to use privileged = true in your Docker containers.

   This also mounts /certs/client for the service and buildcontainer, which is needed for the Docker client to use thecertificates inside of that directory. For more information on howDocker with TLS works, check https://hub.docker.com/_/docker/#tls.

   The above command creates a config.toml entry similar to this:

3. You can now use docker in the build script (note the inclusion of thedocker:19.03.12-dind service):

TLS disabled

Sometimes there are legitimate reasons why you might want to disable TLS.For example, you have no control over the GitLab Runner configurationthat you are using.

Assuming that the runner's config.toml is similar to:

You can now use docker in the build script (note the inclusion of thedocker:19.03.12-dind service):

Use Docker socket binding

The third approach is to bind-mount /var/run/docker.sock into thecontainer so that Docker is available in the context of that image.

NOTE: Note:If you bind the Docker socket when using GitLab Runner 11.11 ornewer,you can no longer use docker:19.03.12-dind as a service because volume bindingsare done to the services as well, making these incompatible.

In order to do that, follow the steps:

1. Install GitLab Runner.

2. Register GitLab Runner from the command line to use docker and share /var/run/docker.sock:

   The above command registers a new runner to use the specialdocker:19.03.12 image which is provided by Docker. Notice that it's usingthe Docker daemon of the runner itself, and any containers spawned by Dockercommands are siblings of the runner rather than children of the runner.This may have complications and limitations that are unsuitable for your workflow.

   The above command creates a config.toml entry similar to this:

3. You can now use docker in the build script (note that you don't need toinclude the docker:19.03.12-dind service as when using the Docker in Dockerexecutor):

While the above method avoids using Docker in privileged mode, you should beaware of the following implications:

• By sharing the Docker daemon, you are effectively disabling allthe security mechanisms of containers and exposing your host to privilegeescalation which can lead to container breakout. For example, if a projectran docker rm -f $(docker ps -a -q) it would remove the GitLab Runnercontainers.

• Concurrent jobs may not work; if your testscreate containers with specific names, they may conflict with each other.

• Sharing files and directories from the source repository into containers may notwork as expected since volume mounting is done in the context of the hostmachine, not the build container. For example:

Making Docker-in-Docker builds faster with Docker layer caching

When using Docker-in-Docker, Docker downloads all layers of your image everytime you create a build. Recent versions of Docker (Docker 1.13 and above) canuse a pre-existing image as a cache during the docker build step, considerablyspeeding up the build process.

How Docker caching works

When running docker build, each command in Dockerfile results in a layer.These layers are kept around as a cache and can be reused if there haven't beenany changes. Change in one layer causes all subsequent layers to be recreated.

You can specify a tagged image to be used as a cache source for the docker buildcommand by using the --cache-from argument. Multiple images can be specifiedas a cache source by using multiple --cache-from arguments. Keep in mind thatany image that's used with the --cache-from argument must first be pulled(using docker pull) before it can be used as a cache source.

Using Docker caching

Here's a .gitlab-ci.yml file showing how Docker caching can be used:

The steps in the script section for the build stage can be summed up to:

1. The first command tries to pull the image from the registry so that it can beused as a cache for the docker build command.
2. The second command builds a Docker image using the pulled image as acache (notice the --cache-from $CI_REGISTRY_IMAGE:latest argument) ifavailable, and tags it.
3. The last two commands push the tagged Docker images to the container registryso that they may also be used as cache for subsequent builds.

Use the OverlayFS driver

NOTE: Note:The shared runners on GitLab.com use the overlay2 driver by default.

By default, when using docker:dind, Docker uses the vfs storage driver whichcopies the filesystem on every run. This is a disk-intensive operationwhich can be avoided if a different driver is used, for example overlay2.

Requirements

1. Make sure a recent kernel is used, preferably >= 4.2.

2. Check whether the overlay module is loaded:

   If you see no result, then it isn't loaded. To load it use:

   If everything went fine, you need to make sure module is loaded on reboot.On Ubuntu systems, this is done by editing /etc/modules. Just add thefollowing line into it:

Use the OverlayFS driver per project

You can enable the driver for each project individually by using the DOCKER_DRIVERenvironment variable in .gitlab-ci.yml:

Use the OverlayFS driver for every project

If you use your own GitLab Runners, youcan enable the driver for every project by setting the DOCKER_DRIVERenvironment variable in the[[runners]] section of config.toml:

If you're running multiple runners, you have to modify all configuration files.

NOTE: Note:Read more about the runner configurationand using the OverlayFS storage driver.

Using the GitLab Container Registry

Once you've built a Docker image, you can push it up to the built-inGitLab Container Registry.

Troubleshooting

docker: Cannot connect to the Docker daemon at tcp://docker:2375. Is the docker daemon running?

This is a common error when you are usingDocker in Dockerv19.03 or higher.

This occurs because Docker starts on TLS automatically, so you need to do some setup.If:

• This is the first time setting it up, carefully readusing Docker in Docker workflow.
• You are upgrading from v18.09 or earlier, read ourupgrade guide.

Sudo apt-get install docker-ce=5:19.03.103-0ubuntu-focal docker-ce-cli=5:19.03.103-0ubuntu-focal containerd.io If you just want to latest version without specifying above, run the commands below. The command below will always install the highest possible version. Install GitLab Runner using the official GitLab repositories. Ubuntu, Mint, RHEL, Fedora, and CentOS. Make sure to install Docker before using GitLab Runner. Docker images; SELinux. 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 (based on Ubuntu or Alpine Linux) are designed as wrappers around the standard gitlab-runner command, like if GitLab Runner was installed directly on the.

• Install the Docker image and start the container

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

I had this problem recently where apt install wget does not find anything. As it turns out apt update was never run. Apt update apt install wget After discussing this with a coworker we mused that apt update is likely not run in order to save both time and space in the docker image. Fedora and RHEL/CentOS users should try disabling selinux with setenforce 0 and check if resolves the issue. If it does than there is not much that I can help you with. You can either stick with selinux disabled (not recommended by redhat) or switch to using ubuntu.

General GitLab Runner Docker image usage

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

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

can be executed with:

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

In short, the gitlab-runner part of the command is replaced withdocker run [docker options] gitlab/gitlab-runner, while the rest of thecommand stays as it is described in the register documentation.The only difference is that the gitlab-runner command is executed inside of aDocker container.

Install the Docker image and start the container

Before you begin, ensure Docker is installed.

To run gitlab-runner inside a Docker container, you need to make sure that the configuration is not lost when the container is restarted. To do this, there are two options, which are described below.

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

Option 1: Use local system volume mounts to start the Runner container

This example uses the local system for the configuration volume that is mounted into the gitlab-runner container. This volume is used for configs and other resources.

Option 2: Use Docker volumes to start the Runner container

In this example, you can use a configuration container to mount your custom data volume.

1. Create the Docker volume:

2. Start the GitLab Runner container using the volume we just created:

Register the runner

The final step is to register a new runner. The GitLab Runner Container won’t pick up any jobs until it’s registered.

Update configuration

If you change the configuration in config.toml, you might need to restart the runner to apply the change.Make sure to restart the whole container instead of using gitlab-runner restart:

Upgrade version

Pull the latest version (or a specific tag):

Stop and remove the existing container:

Start the container as you did originally:

Reading GitLab Runner logs

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

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

Configure Gitlab Runner Docker Download

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

you may get the logs with:

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

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

Installing trusted SSL server certificates

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

The gitlab/gitlab-runner image is configured to look for the trusted SSLcertificates 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 youwant GitLab Runner to trust. The GitLab Runner container willimport the ca.crt file on startup so if your container is already running youmay need to restart it for the changes to take effect.

Docker images

The following multi-platform Docker images are available:

• gitlab/gitlab-runner:latest based on Ubuntu.
• gitlab/gitlab-runner:alpine based on Alpine with much a smaller footprint(~160/350 MB Ubuntu vs ~45/130 MB Alpine compressed/decompressed).

See GitLab Runnersource for possible build instructions for both Ubuntu and Alpine images.

SELinux

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

Special care must be taken when dealing with such a configuration.

1. If you want to use the Docker executor to run builds in containers, you’ll need access to /var/run/docker.sock.However, if SELinux is in enforcing mode, you will see a Permission denied error when you’re accessing /var/run/docker.sock.Install selinux-dockersock to resolve this issue.
2. Make sure that a persistent directory is created on host: mkdir -p /srv/gitlab-runner/config.
3. Run Docker with :Z on volumes:

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/

Help & feedback

Get Help

If you didn't find what you were looking for,search the docs.

If you want help with something specific and could use community support,post on the GitLab forum.

Install Gitlab Docker Ubuntu

For problems setting up or using this feature (depending on your GitLabsubscription).

Install Gitlab Docker Ubuntu Free

Estimated reading time: 7 minutes

You can run Compose on macOS, Windows, and 64-bit Linux.

Prerequisites

Docker Compose relies on Docker Engine for any meaningful work, so make sure youhave Docker Engine installed either locally or remote, depending on your setup.

• On desktop systems like Docker Desktop for Mac and Windows, Docker Compose isincluded as part of those desktop installs.

• On Linux systems, first install theDocker Enginefor your OS as described on the Get Docker page, then come back here forinstructions on installing Compose onLinux systems.

• To run Compose as a non-root user, see Manage Docker as a non-root user.

Install Compose

Follow the instructions below to install Compose on Mac, Windows, Windows Server2016, or Linux systems, or find out about alternatives like using the pipPython package manager or installing Compose as a container.

Install a different version

The instructions below outline installation of the current stable release(v1.28.6) of Compose. To install a different version ofCompose, replace the given release number with the one that you want. Composereleases are also listed and available for direct download on theCompose repository release page on GitHub.To install a pre-release of Compose, refer to the install pre-release buildssection.

Install Compose on macOS

Docker Desktop for Mac includes Compose alongwith other Docker apps, so Mac users do not need to install Compose separately.For installation instructions, see Install Docker Desktop on Mac.

Install Compose on Windows desktop systems

Docker Desktop for Windows includes Composealong with other Docker apps, so most Windows users do not need toinstall Compose separately. For install instructions, see Install Docker Desktop on Windows.

If you are running the Docker daemon and client directly on MicrosoftWindows Server, follow the instructions in the Windows Server tab.

Install Compose on Windows Server

Follow these instructions if you are running the Docker daemon and client directlyon Microsoft Windows Server and want to install Docker Compose.

1. Start an “elevated” PowerShell (run it as administrator).Search for PowerShell, right-click, and chooseRun as administrator. When asked if you want to allow this appto make changes to your device, click Yes.

2. In PowerShell, since GitHub now requires TLS1.2, run the following:

   Then run the following command to download the current stable release ofCompose (v1.28.6):

Note: On Windows Server 2019, you can add the Compose executable to $Env:ProgramFilesDocker. Because this directory is registered in the system PATH, you can run the docker-compose --version command on the subsequent step with no additional configuration.

1. Test the installation.

Install Compose on Linux systems

On Linux, you can download the Docker Compose binary from theCompose repository release page on GitHub.Follow the instructions from the link, which involve running the curl commandin your terminal to download the binaries. These step-by-step instructions arealso included below.

For alpine, the following dependency packages are needed:py-pip, python3-dev, libffi-dev, openssl-dev, gcc, libc-dev, rust, cargo and make.

1. Run this command to download the current stable release of Docker Compose:

   To install a different version of Compose, substitute 1.28.6with the version of Compose you want to use.

   If you have problems installing with curl, seeAlternative Install Options tab above.

2. Apply executable permissions to the binary:

Note: If the command docker-compose fails after installation, check your path.You can also create a symbolic link to /usr/bin or any other directory in your path.

For example:

1. Optionally, install command completion for thebash and zsh shell.

2. Test the installation.

Alternative install options

Install using pip

For alpine, the following dependency packages are needed:py-pip, python3-dev, libffi-dev, openssl-dev, gcc, libc-dev, rust, cargo, and make.

Configure Gitlab Runner Docker Software

Compose can be installed frompypi using pip. If you installusing pip, we recommend that you use avirtualenv because many operatingsystems have python system packages that conflict with docker-composedependencies. See the virtualenvtutorial to getstarted.

If you are not using virtualenv,

Config Gitlab Runner Docker

pip version 6.0 or greater is required.

Install as a container

Compose can also be run inside a container, from a small bash script wrapper. Toinstall compose as a container run this command:

Install pre-release builds

If you’re interested in trying out a pre-release build, you can download releasecandidates from the Compose repository release page on GitHub.Follow the instructions from the link, which involves running the curl commandin your terminal to download the binaries.

Pre-releases built from the “master” branch are also available for download athttps://dl.bintray.com/docker-compose/master/.

Pre-release builds allow you to try out new features before they are released,but may be less stable.

Upgrading

Configure Gitlab Runner Docker Free

If you’re upgrading from Compose 1.2 or earlier, remove ormigrate your existing containers after upgrading Compose. This is because, as ofversion 1.3, Compose uses Docker labels to keep track of containers, and yourcontainers need to be recreated to add the labels.

If Compose detects containers that were created without labels, it refusesto run, so that you don’t end up with two sets of them. If you want to keep usingyour existing containers (for example, because they have data volumes you wantto preserve), you can use Compose 1.5.x to migrate them with the followingcommand:

Alternatively, if you’re not worried about keeping them, you can remove them.Compose just creates new ones.

Uninstallation

To uninstall Docker Compose if you installed using curl:

To uninstall Docker Compose if you installed using pip:

Got a “Permission denied” error?

If you get a “Permission denied” error using either of the abovemethods, you probably do not have the proper permissions to removedocker-compose. To force the removal, prepend sudo to either of the abovecommands and run again.

Setup Gitlab Runner Docker Executor

Where to go next

Configure Gitlab Runner Docker Windows 10