mitchese/gitlab-ci-multi-runner-latex:10.0.2
Introduction
This is an extension of sameersbn's excellent gitlab-ci-multirunner, built for accepting LaTeX builds from Gitlab-CI. I'm using Gitlab to track documents such as my Resume, then gitlab-ci to automatically build a PDF from my resume upon checkin.
A full description of how to use this can be found on my blog post here.
Getting started
Installation
A finished image of this is available on Dockerhub and is the recommended method of installation.
docker pull mitchese/gitlab-ci-multi-runner-latex:latest
Alternatively you can build the image yourself.
docker build -t mitchese/gitlab-ci-multi-runner-latex github.com/mitchese/docker-gitlab-ci-multi-runner-latex
Quickstart
Before a runner can process your CI jobs, it needs to be authorized to access the the GitLab CI server. The CI_SERVER_URL
, RUNNER_TOKEN
, RUNNER_DESCRIPTION
and RUNNER_EXECUTOR
environment variables are used to register the runner on GitLab CI.
docker run --name gitlab-ci-multi-runner-latex -d --restart=always \
--volume /srv/docker/gitlab-runner:/home/gitlab_ci_multi_runner/data \
--env='CI_SERVER_URL=http://git.muzik.ca/ci' --env='RUNNER_TOKEN=xxxxxxxxx' \
--env='RUNNER_DESCRIPTION=latexbuilder' --env='RUNNER_EXECUTOR=shell' \
mitchese/gitlab-ci-multi-runner-latex:latest
Update the values of CI_SERVER_URL
, RUNNER_TOKEN
and RUNNER_DESCRIPTION
in the above command. If these enviroment variables are not specified, you will be prompted to enter these details interactively on first run.
Once the runner is registered with gitlab, add the following configuration to .gitlab-ci.yaml in the root of your git repo to instruct gitlab how to do an automatic build pipeline:
job:
tags:
- latex
when: manual
script:
- for i in *.tex; do lualatex $i; done
artifacts:
paths:
- ./*.pdf
expire_in: 1 week
Persistence
For the image to preserve its state across container shutdown and startup you should mount a volume at /home/gitlab_ci_multi_runner/data
.
The Quickstart command already mounts a volume for persistence.
SELinux users should update the security context of the host mountpoint so that it plays nicely with Docker:
mkdir -p /srv/docker/gitlab-runner
chcon -Rt svirt_sandbox_file_t /srv/docker/gitlab-runner
Deploy Keys
At first run the image automatically generates SSH deploy keys which are installed at /home/gitlab_ci_multi_runner/data/.ssh
of the persistent data store. You can replace these keys with your own if you wish to do so.
You can use these keys to allow the runner to gain access to your private git repositories over the SSH protocol.
NOTE
- The deploy keys are generated without a passphrase.
- If your CI jobs clone repositories over SSH, you will need to build the ssh known hosts file which can be done in the build steps using, for example,
ssh-keyscan github.com | sort -u - ~/.ssh/known_hosts -o ~/.ssh/known_hosts
.
Trusting SSL Server Certificates
If your GitLab server is using self-signed SSL certificates then you should make sure the GitLab server's SSL certificate is trusted on the runner for the git clone operations to work.
The runner is configured to look for trusted SSL certificates at /home/gitlab_ci_multi_runner/data/certs/ca.crt
. This path can be changed using the CA_CERTIFICATES_PATH
enviroment variable.
Create a file named ca.crt
in a certs
folder at the root of your persistent data volume. The ca.crt
file should contain the root certificates of all the servers you want to trust.
With respect to GitLab, append the contents of the gitlab.crt
file to ca.crt
. For more information on the gitlab.crt
file please refer the README of the docker-gitlab container.
Similarly you should also trust the SSL certificate of the GitLab CI server by appending the contents of the gitlab-ci.crt
file to ca.crt
.
Maintenance
Upgrading
To upgrade to newer releases:
- Download the updated Docker image:
docker pull mitchese/gitlab-ci-multi-runner-latex:latest
- Stop the currently running image:
docker stop gitlab-ci-multi-runner-latex
- Remove the stopped container
docker rm -v gitlab-ci-multi-runner-latex
- Start the updated image
docker run -name gitlab-ci-multi-runner-latex -d \
[OPTIONS] \
mitchese/gitlab-ci-multi-runner-latex:latest