MkDocsをGitLab上で構築する。

MkDocsをGitLab Pagesに移行したついでに、ビルドデプロイをGitLab CIを使って自動化、Dockerを使ってビルド環境も自動で整えてみました。

構成

GitLab上では2つのリポジトリを作成します。それぞれ

• MkDocsをビルドするためのDockerイメージを作成するリポジトリ
• MkDocsをビルドしてGitLabPageにデプロイするドキュメント本体のリポジトリ

になっており、ビルド環境と、ドキュメント本体のリポジトリを分けています。

MkDocsをビルドするためのDockerイメージを作成するリポジトリ

まずは、MkDocsのビルドを動かすためのDockerイメージを作成するリポジトリを作ります。DockerとはDocker社が開発しているコンテナ型の仮想環境で、このDockerを使ってLinuxの仮想環境を作りそのなかでMkDocsをビルドします。Dockerではミドルウェアのインストールや各セットアップがコードで記述できるので、MkDocsをビルドするために必要なパッケージを自動的にセットアップさせることができます。

Dockerfileの作成

まず、GitLab上で新たにリポジトリを作成します。作成が完了したら、そのリポジトリにDockerfileという名前のファイルを追加します。Dockerfileはセットアップされた仮想環境であるDockerイメージを作るための設計図です。Dockerfileを作成しビルドすることで自分好みの設定のDockerイメージを作ることができます。Dockerfileに以下を記述します。

# DockerHubにあるAlpine LinuxのPython環境を元にする。
FROM python:alpine

# MkDocsに含まれるregexをビルドするためのgccがないのでインストール
RUN apk add build-base

# mkdocsをインストール
RUN pip install --upgrade pip \
  && pip install mkdocs \
  && pip install mkdocs-material

# ローカルでテストするための設定
WORKDIR /root
CMD ["mkdocs", "serve", "-a", "0.0.0.0:8000"]

このDockerfileで、AlpineというLinuxでMkDocsをビルドするための環境設定が出来ました。

.gitlab-ci.ymlの作成

次にDockerfileを使ってGitLab-CI上でDockerイメージを作成するための設定ファイルを書きます。リポジトリに新たに.gitlab-ci.ymlファイルを追加します。このファイルにはGitLab-CIで行うジョブの設定を記述します。設定内容は以下になります。

GitLab Container Registryとは、リポジトリにDockerイメージを公開できる機能です。GitLab-CIでDockerfileをビルドして、GitLab Container Registryにpushします。pushするためのURLはリポジトリのメニューのPackages & Registriesからコンテナレジストリを開くと、赤丸で囲ったところにコンテナレジストリイメージを追加するためのコマンドが表示されています。

このコマンドを使って、以下のような.gitlab-ci.ymlを作成します。

build:
    image: docker:latest
    stage: build
    services:
        - docker:dind
    script:
        - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
        - docker build -t [GitLab Container Registry のURL] .
        - docker push [GitLab Container Registry のURL]

このCIの処理としては、docker:latestのDockerイメージを使用して、docker:dindというDockerコンテナの中でDockerを使用できるサービスを指定します。そのあとscript:ブロックで、dockerへのログイン、dockerイメージのビルド、GitLab Container Registryにプッシュを行います。

Dockerfile、.gitlab-ci.ymlをリポジトリにプッシュすればCIが動きだし、ビルドが始まります。始まらない場合はRunnerが設定されているか確認してください。

MkDocsをビルドしてGitLabPageにデプロイするドキュメント本体のリポジトリ

次に先ほど作ったDockerイメージを使ってMkDocsをビルドし、成果物をGitLabPageにデプロイするリポジトリを作成します。ドキュメント本体を管理するのもこのリポジトリです。

.gitlab-ci.ymlの作成

ここのCIで指定するのは、Dockerイメージを使ってMkDocsをビルドし、成果物をGitLabPageにデプロイする処理です。以下のように書きます。

variables:
    DOC_IMAGE_TAG: [GitLab Container Registry のURL]

stages:
    - docker
    - build
    - release

document:
    stage: docker
    image: docker:latest
    services:
        - docker:dind
    before_script:
        - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    script:
        - docker pull $DOC_IMAGE_TAG || true

document:build:
    stage: build
    image: $DOC_IMAGE_TAG
    before_script:
    script:
        - mkdocs build
    artifacts:
        paths:
            - site/
        expire_in: 10 min

pages:
    stage: release
    script:
        - mv site public
    artifacts:
        paths:
            - public/
    dependencies:
        - document:build
    only:
        - master

この処理は3つのステージに分かれており、1つ目のdockerステージでは、先ほどと同様docker:dindを使って、GitLab Container Registryから、作ったDockerイメージをプルしてきます。2つ目のbuildステージでは、プルしてきたDockerイメージを起動し、mkdocs buildを実行してMkDocsのサイトを生成します。成果物のパスを次のジョブに渡します。3つ目のreleaseステージでは、siteフォルダ以下のファイルをpublicフォルダに移します。

そのあとはGitLabが自動でpublicフォルダの変更を検知し、Pagesにデプロイしてくれます。

ローカルビルドする

ここで作成したDockerImageはローカルで実行して、ローカルサーバー上でMkDocsのテストができるようになっています。

以下のコマンドをMkDocsのディレクトリ上で実行すると、DockerfileからDockerイメージをビルドし、MkDocsのテストサーバーを立ち上げます。

docker build -t mkdocs -f [Dockerfileのパス] .

docker run -p 8000:8000 -v %CD%:/root mkdocs

ビルドされたページはlocalhost:8000でWebブラウザで確認できます。

停止したい場合は以下のコマンドを実行します。

docker stop mkdocs_serve

Dockerイメージの削除まで行いたい場合は以下のコマンドを実行します

docker rm mkdocs_serve