|
|
|
|
|
# Setting Up a Remote Runner to Build PDF Documents
|
|
|
# Setting Up a Remote Runner to Build PDF Documents {ignore=true}
|
|
|
|
|
|
## Purpose
|
|
|
## Purpose {ignore=true}
|
|
|
|
|
|
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
|
|
|
## Prerequisities {ignore=true}
|
|
|
|
|
|
- GitLab account
|
|
|
- Laptop with admin access
|
... | ... | @@ -13,13 +13,7 @@ In this tutorial we are going to setup GitLab and a remote computer (can also be |
|
|
|
|
|
## 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
|
|
|
[TOC]
|
|
|
|
|
|
## Create New Project in GitLab
|
|
|
|
... | ... | @@ -71,7 +65,7 @@ At the end of the provisioning of your droplet you will get an IP address. You w |
|
|
Now from the command line log into your new droplet.
|
|
|
|
|
|
```bash
|
|
|
$ ssh root@165.227.141.153
|
|
|
$ ssh root@165.227.141.153
|
|
|
```
|
|
|
|
|
|
If everything works out fine, you should have logged into your droplet![^1]
|
... | ... | @@ -81,3 +75,76 @@ 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](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. 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](https://docs.gitlab.com/runner/install/linux-repository.html):
|
|
|
|
|
|
```bash
|
|
|
$ 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*.
|
|
|
|
|
|
![runner-token](/assets/runner-token.png)
|
|
|
|
|
|
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
|
|
|
|
|
|
```bash
|
|
|
$ 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:
|
|
|
|
|
|
```yaml
|
|
|
# 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! |