|
|
|
|
|
# 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](https://www.docker.com/what-docker)
|
|
|
|
|
|
## Steps
|
|
|
|
|
|
- Create new project in GitLab
|
|
|
- Commit a minimum of source code for LaTeX or Markdown to the repository
|
|
|
- Prepare a remote machine
|
|
|
- Download and install GitLab runner
|
|
|
- Register a new runner
|
|
|
- Configure GitLab to communicate with the runner
|
|
|
- Enjoy
|
|
|
|
|
|
## 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](https://collaborating.tuhh.de/xldrkp/remote-runner-example).
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
```latex
|
|
|
\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)](https://www.digitalocean.com/), 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](https://www.digitalocean.com/referral-program/).
|
|
|
|
|
|
### 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](http://gitkraken.com/). If you don't know what this is all about read [this tutorial from GitLab](https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html#how-to-create-your-ssh-keys).
|
|
|
- Give your droplet a name. I chose `remote-gitlab-runner`
|
|
|
- Create the droplet!
|
|
|
|
|
|
## Download and install GitLab runner
|
|
|
|
|
|
Now you need to download and install [the GitLab Runner](https://docs.gitlab.com/runner/) once on a machine you own or controll. This could be your laptop or a remote machine that is capable of running [Docker](https://de.wikipedia.org/wiki/Docker_(Software)). We will use Docker images to run *pdflatex* or *Pandoc* for building our documents. |