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!1
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.↩