@kyanny's blog

My thoughts, my life. Views/opinions are my own.

gollum と plantuml-server をローカルマシンで動かす

ローカルマシン上で起動する

gollum は PlantUML をサポートしている。デフォルトでは http://www.plantuml.com/ を変換サーバーとして用いるが*1、 PlantUML サーバーの URL を変更することができる。

config.rb

Gollum::Filter::PlantUML.configure do |config|
  config.url = "http://localhost:8080/plantuml/png"
end

$ gollum --host=127.0.0.1 --config=config.rb path/to/git-repo-of-wiki

PlantUML Server は GitHub で公開されており、ローカルマシン上で変換サーバーを起動できる。デフォルトでは http://localhost:8080/plantuml で起動する。

$ git clone https://github.com/plantuml/plantuml-server
$ cd plantuml-server
$ mvn jetty:run

PlantUML Server をローカルマシン上で起動することで、外部との通信なしに図表を表示できる。

Docker を使う場合の注意点

plantuml-server は Dockerfile を提供している。 Docker を使うとローカルマシンの環境を汚さずに済むが、 PlantUML Server の URL の扱いに注意点がある。

  1. plantuml-server の Docker イメージを使うと http://localhost:8080/ をルート URL として起動する。 gollum は /plantuml というパスをルート URL として期待するので、 BASE_URL を渡して URL のパスを調整する必要がある。
  2. gollum と plantuml-server はそれぞれ別のコンテナで起動するので、 gollum から localhost で通信できず、 Sorry, unable to render PlantUML diagram at this time エラーが発生する。 gollum から http://plantuml-server:8080/ のようにコンテナ名を指定すれば通信可能だが、 IMG タグの SRC 属性として出力される URL も http://plantuml-server:8080/ で始まるものになってしまう。ホストマシンにその URL を解釈させるためにはホストマシンの /etc/hosts に追記が必要。

docker-compose.yml

version: "3.8"

services:
  gollum:
    image: suttang/gollum
    container_name: gollum
    restart: always
    ports:
      - "4567:4567"
    volumes:
      - ${PWD}/config.rb:/etc/gollum/config.rb
      - ${PWD}:/root/wikidata
    command:
      - "--config=/etc/gollum/config.rb"
  plantuml-server:
    image: plantuml/plantuml-server
    container_name: plantuml-server
    build:
      context: https://github.com/plantuml/plantuml-server.git
      dockerfile: Dockerfile.jetty
      args:
        BASE_URL: plantuml
    ports:
      - "8080:8080"

config.rb

Gollum::Filter::PlantUML.configure do |config|
  config.url = "http://plantuml-server:8080/plantuml/png"
end

/etc/hosts

127.0.0.1 plantuml-server

結論

gollum も plantuml-server もおとなしくローカルマシン上で直接起動するのが、手間が少なくて楽。常用する場合、それぞれポート番号は変更した方が良い。

Vagrant を使ってバーチャルマシン上で実行する方法もあるが、マシンリソースを食うし、セットアップの手間も若干増すので、どうしてもローカルマシンの環境を汚したくない強い動機でもなければ、あまりメリットはない。

Docker を使う方法は、ホストマシンの /etc/hosts を書き換える必要があり、最もスマートさに欠ける。良い回避策があれば良いのだが。

余談

gollum の wiki には By default gollum-lib expects the PlantUML server to be located on http://localhost:8080/plantuml/png. とある。しかし gollum-lib v5.0 以降はデフォルトの PlantUML Server に https://plantuml.com/ を使うように変更された。

ところが、 gollum の wiki でも Most starts と勧められている suttang/gollum という Docker イメージは gollum v4.0.1 をインストールする。 Docker イメージの最終更新日が五年前だからだろう。

gollum プロジェクトがオフィシャルの Docker イメージを提供しようとしている形跡がある。 Ruby のバージョンも新しいので、今後はこちらを使う流れになるのかもしれない（suttang/gollum は Ruby 1.9.3 を使っている）。

参考リンク

*1:gollum-lib のバージョンによる。余談の項を参照のこと。