DEV Community

Cover image for GitLab Runner on Raspberry Pi 4 (Build, Push Docker images to Docker Hub using GitLab Runner on GitLab)
Omar Omar
Omar Omar

Posted on

GitLab Runner on Raspberry Pi 4 (Build, Push Docker images to Docker Hub using GitLab Runner on GitLab)

What is GitLab Runner

GitLab Runner is an agent that runs GitLab CI/CD (Continues Integration/Continuous Deployment) jobs in a pipeline. It's heavily utilized in the world of DevOps to provision and configure infrastructure. The GitLab Runner can be installed as a binary on Linux, MacOS or Windows. It can also be installed as a container.

On this tutorial, I will walk through installing and configuring GitLab Runner as a container using a Docker image on a RPI-4..yaay. I will make it very swift to get you started and won't feel a thing. I will not bore you with details, but if there are useful links for further study, I will definitely throw it in. The goal is to get you started with GitLab Runners and the rest is on you.

As a bonus, we will run our first job of building docker images and push them to Docker hub. Enough reading, let's get our hands dirty, I mean our keyboards 😉

To lean more about GitLab Runners, refer to GitLab official documentation.

Note: Sensitive information will be pixilated or erased. This should not alter the quality of the tutorial.

Run a GitLab Runner Container on a RPI-4

If you don't have Docker installed on your RPI-4, you may refer to my Docker on Ubuntu 20.04 Raspberry Pi 4 tutorial.

1- Let's create a persistent Docker volume for the runner. On your RPI-4 terminal, run the following command:

docker volume create gitlab-runner-volume
Enter fullscreen mode Exit fullscreen mode

Note: you can change the volume name gitlab-runner-volume to any name of your chosen, but you should be consistent as we will use the volume name to bind the container to the RPI-4 local host.

2- Run the below commands to start GitLab Runner container:

docker run -d --name gitlab-runner --restart always --env TZ=US \
   -v  gitlab-runner-volume:/etc/gitlab-runner \
   -v /var/run/docker.sock:/var/run/docker.sock \
Enter fullscreen mode Exit fullscreen mode

The only parameters you have the options to change are:

  • the name flag, gitlab-runner
  • the volume name, gitlab-runner-volume
  • the gitlab runner image, gitlab/gitlab-runner:alpine
  • the env flag, TZ=US

For more information about the installation process, here is the link GitLab's official documentation.

3- Capture the GitLab Runner token:

We do need to head to our GitLab account and grab the runner's token. If you don't have a GitLab account, you can create one for free. Here is the link.

Now, we need to create a repository to host our project. From GitLab, let's click on create New project. On the Create new project, select create blank project. Then, give the project a name and click Create project. In my case, I named my repo, GitLab-Runner-RPI-4.

Image description

From the repository, let's click on settings, CI/CD and then Expand on the Runners section as shown below.

Image description

  • Capture the token and save it on a note pad. We will need the token for the next step.
  • Disable Enable shared runners for this project.

Image description

4- Register the GitLab Runner:

Replace the token place holder after registration-token with the one from our note pad, and then run the following commands on your RPI-4 terminal:

docker run --rm -it -v gitlab-runner-volume:/etc/gitlab-runner gitlab/gitlab-runner:alpine register -n \
  --url \
  --registration-token GR1348941EDhyNWqfxPttukrGVKJd \
  --executor docker \
  --description "My Docker Runner" \
  --docker-image "docker:20.10.12-dind-alpine3.15" \
  --docker-privileged \
  --docker-volumes "/certs/client"
Enter fullscreen mode Exit fullscreen mode

If everything went smooth, you should not exhibit no errors as shown below.

Image description

To confirm that the GitLab Runner container is running, run the below Docker command:

docker ps -a
Enter fullscreen mode Exit fullscreen mode

Image description

Alright, this is a great indication that we have successfully configured GitLab Runner on RPI-4. Now, we are ready to make some actions 💥

Build and Push Docker images to Docker Hub using GitLab Runner on GitLab

1- First of all, we need get a token from our Docker hub account to avoid using account password. The token is to allow GitLab Runner to authenticate and push Docker images to our Docker hub repository. If you don't know what Docker hub is, it is the world's largest library for container images.

On Docker hub account settings, click on Security, New Access Token and generate a Read, Write, Delete token. Docker hub free account allows for one active token. Capture the token and save to a note pad.

Image description

2- From GitLab repo, which have we have created previously:

  • Click on Clone and copy the Clone with HTTPS link.
  • On your RPI-4 terminal and in a folder of your chosen, run the below command. This is where the repo will be saved locally:
git clone `your-Clone-with-HTTPS-link`
Enter fullscreen mode Exit fullscreen mode

Note: the git clone command will prompt you to enter your GitLab credentials for authentication.

Image description

3- cd into the repo and either use a text editor or the terminal to edit the .gitlab-ci.yml file. The file should only contain the following code. Be very careful with the indentation. Lastly, save the file:

image: docker:19.03.12

    IMAGE_NAME: "test:1.0.0"
    DOCKER_TLS_CERTDIR: "/certs"

    - docker:19.03.12-dind
  - docker info
build image:
    stage: build 
        - docker build -t $REGISTRY_USER/$IMAGE_NAME .
        - docker login -u $REGISTRY_USER -p $DOCKER_HUB_TOKEN
        - docker push $REGISTRY_USER/$IMAGE_NAME
Enter fullscreen mode Exit fullscreen mode

Image description

4- We will create a simple Dockerfile. The runner will use this Dockerfile to build a Docker image and push it to Docker hub. For right now, we will keep the Dockerfile VERY simple. Once the image is built from the Dockerfile, it will echo Hello World.
With your preferred text editor or terminal, create and name a file Dockerfile without any extension. Then save it in the same local repo.

FROM alpine
RUN echo "Hello World"
Enter fullscreen mode Exit fullscreen mode

Note: In the local repo, we should have two files, Dockerfile and .gitlab-ci.yml. A README file might be there as well.

5- We will need to head back to GitLab repo to create two variables. On Settings, click on CI/CD, then expand Variables. We will click on Add variable to create two variables:

    Value: your Docker hub username NOT the email

    Value: the token which we generated from Docker hub

Note: the flags should be unchecked for simplicity for the two variables.

Image description

Image description

Image description

6- Now, we push the local repo to GitLab repo (remote repo) to start the GitLab Runner pipeline process. Yes, once the remote repo is updated, the runner will be triggered. Let's get back to our terminal on the RPI-4 and from within the local repo, run the following git commands:

git add -A
git commit -am "first test"
git push
Enter fullscreen mode Exit fullscreen mode

If you head back to our GitLab repo and click on CI/CD under Pipelines, you would notice that the pipeline is running.

Image description

Moreover, if you click on the running status and you would be directed to the current stage, which is Build.

Image description

Here, click on build image, you shall see more details about the current build status. The goal is to see Job succeeded.

Image description

Once you see Job succeeded and passed status in green, you can start doing your victory dance 👯 👯

Image description

If we head back to Docker hub account, we should see that our Docker image test:1.0.0 has been successfully pushed to the repo.

Image description


By the end of this tutorial, we have successfully configured a GitLab Runner on a RPI-4, created a GitLab repo and registered GitLab Runner to it. Finally, we created a Hello World Docker image from a Dockerfile and had the runner building the Docker image and pushing it to our Docker hub account.
Now, off you go and the sky is the limit.

Top comments (0)