Posts for: #Mdbook

1日中ドキュメントを書いていた

#mdbook  #document  #event 

一昨日あまり寝てなかったので昨日は早く帰ってきて20時から22時ぐらいまで寝て、その後0時ぐらいから寝て何度か起きて7時に起きた。久しぶりによく寝た。

プロダクトのドキュメント

プロダクトのインストールや設定のドキュメントを mdBook で書いている。チームのメンバーが reStructuredText を知らないというので markdown で書ける方がいいかと思って採用した。4月上旬から環境作り して時間のあるときに少しずつ書き足したり、メンバーにも書いてもらうように促したりしていた。情報としてはだいたい半分ぐらい書けたかなぁといったところ。まだまだ内容は足りていない。

内容とは別に、ある程度まとまったドキュメントとしてのわかりやすさを、例えば Sphinx のようなツールと比較してどうかというのを書き終えたら比較してみようと思う。1つ懸念点としてわかったことに SUMMARY.md からリンクされていない md ファイルはレンダリングされないという仕様になっていて、この仕様の是非や目次の作り方の構成に制約が課せられることへの懸念がある。次の issue でも議論されている。

mdbook は私が想定したほど普通のドキュメントツールが備えているような機能を実装していなくて、それは markdown を独自拡張したくないという意志なのかもしれないけれど、本当に最低限の体裁だけでドキュメントのようにみえるようにするといったところしか関心がないのかもしれない。ちょっと触った雰囲気でも本格的なドキュメントを書くツールではないと感じている。私がまだわかっていないだけかもしれないのでもうちょっと触ってみてまた所感をまとめる。

チーム勉強会

2週間ぶりのチーム勉強会。メンバーが Stable Diffusion の話しをしてくれた。学生時代に関連する研究をしていたらしい。本人は研究していたから内容を理解しているのだろうけど、一般人の私には全然ついていけなくて説明そのものが難しいなと思いながら聞いていた。そして、最近の研究成果などを紹介しながら15分ぐらいで終わった。論文の内容を理解できているのなら、その内容を解説してもよかったのでは？と思ったりもした。1時間の枠があるのだからもっと話してもらってよかったのだけど、準備も大変だったのかもしれない。時間が余っていたので私がモデレーターとして質問したり、他の参加者に質問を促したりしながら残り時間の40分ほど雑談していた。そういう意味では雑談会としては多くの質問やコメントが出てよかったと思う。意図的に発表時間を短くして雑談会にもっていくというやり方もあるのかな？と勉強会の運営の学びにもなった。

ローカルにコンテナレジストリを構築する

#docker  #packaging  #mdbook  #document  #mermaid 

出張する日は寝ないで資料を作ったりバグ修正したりして始発の新幹線の中で寝てた。寝てなくて疲れているせいか、新幹線で寝るのに慣れたのか、わりと2-3時間ぐっすり新幹線で眠れるようになってきた。普通にベッドで寝ても3時間ぐらいしか眠れないので睡眠時間はあまり変わらない。

docker registry の構築

先日の調査 の続き。Deploy a registry server に書いてあることを実際にローカルで検証した。

tls の自己証明書の作成。subjectAltName という設定をするように書いてある。

$ openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key -addext "subjectAltName = DNS:myhost.mydomain.example.com" -x509 -days 365 -out certs/domain.crt

basic 認証のための htpasswd の設定。htpasswd とか懐かしいなと思いながら実行した。

$ docker run --entrypoint htpasswd httpd:2 -Bbn user1 secret1 >> dot_htpasswd
$ docker run --entrypoint htpasswd httpd:2 -Bbn user2 secret2 >> dot_htpasswd

docker 社が提供する oss な docker registry サーバーを使って起動する。

$ mkdir /mnt/registry  # docker image を永続化する場所
$ sudo docker run -d \
  --restart=always \
  --name registry \
  -v "$(pwd)"/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/dot_htpasswd" \
  -v "$(pwd)"/certs:/certs \
  -e "REGISTRY_HTTP_ADDR=0.0.0.0:443" \
  -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt" \
  -e "REGISTRY_HTTP_TLS_KEY=/certs/domain.key" \
  -p 8443:443 \
  -v /mnt/registry:/var/lib/registry \
  registry:2

これで basic 認証付きで https で通信できる docker registry サーバーができた。

外部のマシンから dokcer login しようとすると次のようなエラーが発生する。

$ docker login myhost.mydomain.example.com:8443
Username: user2
Password: ***
Error response from daemon: Get "https://myhost.mydomain.example.com:8443/v2/": x509: certificate signed by unknown authority

Test an insecure registry によると、自己証明書を使って外部からアクセスできるようにするためには docker client 側にさっき作った domain.crt をコピーする必要がある。

linux だとこんな設定。

$ cp domain.crt /etc/docker/certs.d/myhost.mydomain.example.com:8443/ca.crt

Docker Desktop for Mac を使っている場合はこんな感じ。

> security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain path/to/certs/domain.crt

これで外部からも docker login して任意の docker image を push/pull できるようになる。docker registry サーバーは Let’s Encrypt をサポートしているそうなので How It Works を参照して設定すればよいと書いてあった。

mdbook の初期設定

mdbook は新しい rust のバージョンだとビルドできなかったりするので rustup を使ってローカルに rustc をインストールするのがよいかもしれない。プラグインとしては mdbook-mermaid を使う。

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ ~/.cargo/bin/rustc --version
$ cargo install mdbook mdbook-mermaid

mdbook-mermaid の設定も簡単でドキュメントルート配下に mermaid の js ファイルを配置すると動いた。

$ vi book.toml
[preprocessor.mermaid]
command = "mdbook-mermaid"

[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]