GitLab Runner on Raspberry Pi 4 (Build, Push Docker images to Docker Hub using GitLab Runner on GitLab)
Tags: raspberrypi, gitlab, devops, cicd
Published: 2022-02-28 04:21:48

## 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 :wink:

To lean more about GitLab Runners, refer to [GitLab official documentation](https://docs.gitlab.com/runner/). 

**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](https://omar2cloud.github.io/rasp/rpidock/) 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
```
**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 \
   gitlab/gitlab-runner:alpine
```

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](https://docs.gitlab.com/runner/install/docker.html). 

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](https://about.gitlab.com/).

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hz20pmjuwsatu7xaoaly.PNG)


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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ksqmmmeo76siv59cricv.PNG)

- 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2r235b5sof2apo0a3z3m.PNG)


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 https://gitlab.com/ \
  --registration-token GR1348941EDhyNWqfxPttukrGVKJd \
  --executor docker \
  --description "My Docker Runner" \
  --docker-image "docker:20.10.12-dind-alpine3.15" \
  --docker-privileged \
  --docker-volumes "/certs/client"
```

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dksylckynj26jllsn2fc.PNG)


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

```
docker ps -a
```


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o46q7swmo2690jns1clf.PNG)

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


---

## 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](https://hub.docker.com/) 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7zhn5y2vjsuhf6oh2lr5.PNG)


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`
```

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g610wz7anqvmnezldlri.PNG)


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

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

services:
    - docker:19.03.12-dind
before_script:
  - docker info
build image:
    stage: build 
    script:    
        - docker build -t $REGISTRY_USER/$IMAGE_NAME .
        - docker login -u $REGISTRY_USER -p $DOCKER_HUB_TOKEN
        - docker push $REGISTRY_USER/$IMAGE_NAME
```


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zbkxk1ak33xi57eo68x6.PNG)


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"
```

**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:

- Key: REGISTRY_USER
  Value: `your Docker hub username NOT the email`

- Key: DOCKER_HUB_TOKEN
  Value: `the token which we generated from Docker hub`

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uvrhm2dsb9cznqcdzsbl.PNG)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5aovq0iin1oooag5iusv.PNG)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4no38k4rasgp4643hl5r.PNG)


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
```

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0q2qxzurzz9365fay04w.PNG)


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



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0gwqvnoigx72i2cd42li.PNG)

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3fi07dc9m2rwae4bo2fx.PNG)

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0cnmz2xaud4wo1d1ykm0.PNG)


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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uif7ojfrktink9py5wq0.PNG)

---

## Conclusion:

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.