はじめに
卒論・修論や最終レポートの季節ですが、学生の皆さんいかがお過ごしでしょうか。こういった文章をLaTeXで書いてGitで管理している学生さん、たくさんいらっしゃると思います。
今日はそんな皆さんの手間を減らすために、GitLabにpushするだけでLaTeXが全自動でコンパイルされるシステムをDockerを使って組み上げていく方法を紹介します。
全体の構成
Docker上にGitLabとGitLab Runnerを用意して、GitLab Runner上でTeX Liveコンテナを動かしてコンパイルする仕組みです。
事前準備
とりあえずDockerとDocker-composeを用意しておきましょう。インストール方法はここでは特に紹介しません。作業ユーザーをdockerグループに所属させておくと、sudoが不要になって便利といえば便利です。それなりにリスクは負うことになりますが。
Docker-composeの準備
docker-compose.yml
とりあえずdocker-compose.ymlを書いていきましょう。GitLab本体と、GitLab Runnerを用意します。バックアップが容易なように、Volumeを作ってマウントしてあげるとよいでしょう。また、GitLab Runner上でTeX Liveコンテナを動かす都合上、Docker in Docker状態になるため、docker.sockを忘れずにマウントしておきます。
version: '2'
services:
gitlab:
restart: always
image: gitlab/gitlab-ce
hostname: localhost
ports:
- "10080:80"
- "10022:22"
volumes:
- conf:/etc/gitlab
- logs:/var/log/gitlab
- data:/var/opt/gitlab
environment:
VIRTUAL_HOST: gitlab.example.com
gitlab-runner:
restart: always
image: gitlab/gitlab-runner:alpine
volumes:
- ci_data:/etc/gitlab-runner
- /var/run/docker.sock:/var/run/docker.sock
volumes:
conf:
logs:
data:
ci_data:
コンテナの起動
Docker-Composeを使っているので、docker-compose.ymlが存在するディレクトリに移動して、以下のコマンド一発で起動できます。
$ docker-compose up -d
GitLab側の準備
まずは管理者ユーザーを作成しましょう。作成できたら管理者ユーザーでログインして、Runner用のトークンを取得します。
Admin Areaに入りRunnersページを見ると、Registration token is xxxxxxxという記述があるので、このトークンを控えておきます。
GitLab Runnerの準備
GitLab Runnerに、Runnerを登録することでCIを走らせることができます。Runner側のコンテナに情報を入力して、登録作業を済ませましょう。
まずはGitLab Runnerのコンテナ名を調べます。
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
cea8d4827c73 gitlab/gitlab-runner:alpine "/usr/bin/dumb-init /" 38 hours ago Up 38 hours gitlab_gitlab-runner_1
今回はgitlab_gitlab-runner_1であるとわかりました。では実際にRunnerを登録します。url欄とregistration-token欄は、実際の環境に合わせて変更してください。コマンドを実行すると対話環境が始まりますが、必要な情報はほとんど引数として与えてしまっているため、終わるまでEnterを連打していれば大丈夫です。Tagに関しては、後で編集できるのでやはり気にしなくてOKです。
$ docker exec -it gitlab_gitlab-runner_1 gitlab-ci-multi-runner register -n \
--url https://gitlab.example.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "LaTeX Runner" \
--docker-image "aruneko/texlive"
リポジトリの準備
latexmkの準備
LaTeXのコンパイルには、おなじみlatexmkを用います。いろいろな状況を勝手に判断して、全自動でTeXファイルからPDFファイルを生成してくれるすごいやつです。texファイルがあるディレクトリと同一の階層に、.latexmkrcを用意しましょう。今回は、uplatex環境を前提としたサンプルをご紹介します。
#!/usr/bin/env perl
$latex = 'uplatex -shell-escape -synctex=1 -halt-on-error';
$latex_silent = 'uplatex -shell-escape -synctex=1 -halt-on-error -interaction=batchmode';
$bibtex = 'upbibtex %O %B';
$biber = 'biber %O --bblencoding=utf8 -u -U --output_safechars %B';
$dvipdf = 'dvipdfmx %O -o %D %S';
$makeindex = 'mendex %O -o %D %S';
$max_repeat = 5;
$pdf_mode = 3;
.gitlab-ci.ymlの準備
latexmkの設定が済んだら、CIの手順書である.gitlab-ci.ymlを準備しましょう。といっても、ビルドはすべてlatexmkが肩代わりしてくれるので、とてもシンプルに記述できます。
今回、TeX Live環境にはhionoさんが作成したDocker Imageを私がフォークしたものを利用します。フォークした理由は単純で、ソースコードを掲載するためのmintedを使う都合でPygmentsをインストールしておきたかったのと、いつも使っているbxjsclsのバージョンを上げておきたかったからです。
今回texファイル名がthesisである前提で書いてありますが、そこは適宜変更してください。
image: aruneko/texlive:latest
compile_uplatex:
script:
- latexmk thesis.tex
artifacts:
paths:
- thesis.pdf
CIの実行
2つの隠しファイルができあがったら、addしてcommitしてpushしましょう。
$ git add .latexmkrc .gitlab-ci.yml
$ git commit -m "CIに対応"
$ git push -u origin master
あとはCIが走るのを眺めるだけです。Pipelinesページで閲覧できます。完成品もここからダウンロードできるようになっています。
おわりに
既存のものをうまく組み合わせて、LaTeXコンパイルを自動化することができました。忙しい季節、少しでも手間を減らして__本質__に集中しましょう！