Setting Up a Remote Runner to Build PDF Documents

Purpose

In this tutorial we are going to setup GitLab and a remote computer (can also be your laptop) to build PDF documents from LaTeX or Markdown sources.

Prerequisities

GitLab account
Laptop with admin access
basic knowledge of Docker

Create New Project in GitLab

That's quite simple, just click the button and go ahead! I created this one as an example for this tutorial.

Commit a minimum of source code for LaTeX or Markdown to the repository

Now let's push some LaTeX to the new repo that we will generate our PDF from.

\documentclass[a4paper,10pt,oneside]{article}

\usepackage[next]{inputenc}
\usepackage[ngerman]{babel}
\usepackage{fontenc}

\author{John Doe}
\date{10.12.2017}

\begin{document}
	\section{Example}
	This is just an example article.
\end{document}

I saved this in the repo by the name document.tex.

Prepare a Remote Machine

For the next steps you need to prepare a computer that is not GitLab. Software and documents are not built in GitLab, but GitLab is the commander of the build process and in our example can receive the generated artefacts.

In my example I show you this step with an account at Digital Ocean (DO), a hoster for virtually anything virtual. There is a price to pay, but that is quite little and you get up and running very fast. I chose DO, because that's usual Linux machines that can show the process best. And what I show should on MacOS as well. Windows - let's see...

Get an Account at Digital Ocean

Quite easy, you can do this on your own. Have yourself invited and both of you will win.

Create Droplet with Docker Preinstalled

Click "Create Droplet"
Choose "One-click apps" and then "Docker 17.x on 16.x" (button label can differ)
Further down choose the $5 pricing
Choose a region nearby. I choose "Frankfurt".
Add an SSH key and check the box. You can use the one that you created with GitKraken. If you don't know what this is all about read this tutorial from GitLab. Be sure not to protect your SSH key with a password!
Give your droplet a name. I chose remote-gitlab-runner
Create the droplet!

At the end of the provisioning of your droplet you will get an IP address. You will need that address to login to your droplet via SSH.

Now from the command line log into your new droplet.

$ ssh root@165.227.141.153

If everything works out fine, you should have logged into your droplet!¹

Download and install GitLab runner

Now you need to download and install the GitLab Runner once on a machine you own or controll. This could be your laptop or a remote machine that is capable of running Docker. We will use Docker images to run pdflatex or Pandoc for building our documents. That's the reason why we chose a DO droplet with Docker preinstalled!

I presume that you are on your machine right now. There, do the following:

Download and install GitLab Runner as described here:

$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
$ sudo apt-get install gitlab-runner

That should be it!

Register a Runner on the Remote Machine

Now it's time to connect GitLab and the remote machine so that GitLab has a companion to do the work building software and documents for her. The connection is based on a token that you'll find in your project settings. Go to Settings -> CI/CD and expand Runners settings.

You will need that token in the next step when registering a new runner.

Start Registering the Runner on the Remote Machine

Go ahead on the remote machine by typing

$ gitlab-runner register

Answer the following questions like so:

gitlab-ci coordinator URL: https://collaborating.tuhh.de/
gitlab-ci token: [your-token]
description: remote-gitlab-runner
tags: myrunner
Whether to run untagged builds: false
Whether to lock the Runner to current project: true
Executor: docker
default Docker image: aergus/latex

You can overwrite the chosen Docker image later in the configuration file.

After a reload of the Runners settings page you should be able to see the new registered runner!

Testing the Runner

Now let's have the build pipeline work for us and see what happens so far. Go to your GitLab project and create a new file. From the templates dropdown chose .gitlab-ci.yml and on the right LaTeX from the list and see that there are many examples for runner configurations. We will make some changes to the file like so:

# This file is a template, and might need editing before it works on your project.
# use docker image with latex preinstalled
# since there is no official latex image, use https://github.com/blang/latex-docker
# possible alternative: https://github.com/natlownes/docker-latex
image: aergus/latex

build:
  script:
    - pdflatex document.tex
  artifacts:
    paths:
      - "*.pdf"
  tags:
      - myrunner

With the tag myrunner GitLab will find the connected runner and start the pipeline to run.

Save the file and head over to the sidebar entries CI/CD -> Pipelines. You should see a label saying Running. Click on it and on the following page again on build and see what happens on your remote machine! Your DO droplet sends back to this window what it's doing over there. Magic! The Docker image I chose for this example is quite huge and take about ten minutes to download. So relax and wait a while.

Finally, if everything works out fine, you should read Job succeeded at the bottom of the log entries.

Have a look to the right of the page and notice the headline Job artifacts. Below, click on Download and receive the built document.

That's it!

I figured out that you might have to explicitly say which SSH key you want to use when logging in. Do this with ssh user@address -i ~/.ssh/name-of-your-keyfile or similar. ↩

remote runner for documents