コンテンツにスキップ

ADR-0032: ドキュメントサイトを Zensical でビルドし、Cloudflare Access を運営者がダッシュボードで設定する

Status

承認

Context

設計の文書（PRD、Design Doc、ADR）を、ビルドしたサイトとして読めるようにする。

Decision

1. ビルドの方法

  • Zensical で docs/ をビルドし、apps/docs-site/ の Worker（fukuemon-dev-docs）から、静的なアセットとして配信する。buddy と設定と手順を共有するためである。
  • 含める文書は、docs/ の PRD、全体の Design Doc、ADR と、シンボリックリンクで指す機能ごとの Design Doc とデザインシステムの文書にする。context/ は含めない。
  • カタログは含めず、design.fukuemon.dev へのリンクを置く。
  • develop への push で check が通ったときにデプロイする。

2. ほかの URL を閉じる

  • Worker の workers_dev と preview_urls を false にする。
    • custom domain 以外の URL（workers.dev の URL とバージョンごとの URL）で開けないようにするためである。

3. アクセスの認証

docs.fukuemon.dev に Cloudflare Access を設定する。
Access は、ビルドしたサイトを開発者向けにし、訪問者や検索に見せないためのものである。
文書の中身の秘密を守るものではない。

  • Access のアプリケーションとポリシーは、Terraform で持たず、運営者が Cloudflare のダッシュボードで設定する。切り替えの多い設定を、apply を通さずに変えられるようにするためである。
    • この決定は、ADR-0005 の管轄の判定の 3（ドメインへの到達に影響するなら Terraform）の例外にする。
    • 例外は、ドキュメントサイトの Access のアプリケーションとポリシーに限る。
  • docs.<zone> の custom domain（cloudflare_workers_custom_domain.docs）は、Terraform で持つ。ホスト名の作成は、ほかのサブドメインと同じ管轄にそろえる。
  • Terraform では、Access と custom domain を作る順序を制御しない。初めて公開するときは、Terraform で custom domain を先に作り、Access は運営者が後から掛けてよい。手順は apps/docs-site/README.md にある。
  • Access をオフにしている間は、ドキュメントサイトを誰でも開ける。文書の原本は公開のリポジトリにあるので、Access をオフにしても、新しく公開される内容は無い。
  • 許可するメールアドレスは、ダッシュボードのポリシーにだけ書く。リポジトリ、Terraform の state、GitHub の secret に置かない。
  • apply 用と deploy 用の token に Access の権限を与えない。

承認の条件

次の 2 つを確認する。

  • Access をオフにする操作が、アプリケーションの削除か、消さずに無効にする設定か。運営者が初めて Access を掛けるときに確認する。無効にする設定があれば、apps/docs-site/README.md の切り替えの手順を、削除から無効に直す。
  • workers_dev と preview_urls を false にした Worker が、custom domain 以外の URL で開けないこと。ドキュメントサイトを公開するときに確認する。

Considered Options

ビルドの方法の選択肢は次のとおり。

選択肢 強み 弱み
採用: Zensical でビルドする buddy と設定、手順、スキルを共有できる Python と uv の依存が増える
Astro の Starlight でビルドする サイトと同じ Astro で、Python が要らない buddy と違う仕組みを保守する。同じリポジトリに、Astro のビルドの方法が 2 つ並ぶ
ドキュメントサイトを作らず、GitHub の上で文書を読む 基盤が増えない Mermaid の図と文書の間のリンクを、1 つのサイトとして辿れない。buddy と手順がそろわない

Access の管理の選択肢は次のとおり。

選択肢 強み 弱み
採用: Access をダッシュボードで設定する オンとオフを、apply を通さずにすぐ切り替えられる。メールアドレスを secret とログのマスクで扱う仕組みが要らない 設定がリポジトリに残らない。Access を掛けるまでと、オフの間は、誰でも開ける
Access を Terraform で持つ 設定がリポジトリに残る。custom domain を Access の後に作る順を depends_on で守れる 切り替えのたびに、コードの変更、pull request、apply の承認が要る。apply 用の token に Access の権限が要る
Terraform で持ち、オンとオフを変数で切り替える 設定がリポジトリに残る。切り替えはコードを変えずに済む 切り替えのたびに apply の workflow の起動と承認が要る。変数の値を GitHub の variable に置く仕組みが増える
custom domain もダッシュボードで作り、Terraform から外す Access と custom domain を作る順を、同じ画面で守れる ほかのサブドメインと、custom domain の管轄が分かれる

Consequences

Positive

  • 運営者が、設計の文書を、検索と目次のあるサイトで読める。
  • ドキュメントサイトのビルドの方法が、buddy と同じになる。
  • 運営者が、apply を通さずに、ダッシュボードで Access のオンとオフを切り替えられる。
  • apply の workflow と token が、メールアドレスと Access の権限を持たない。

Negative

  • Python と uv が、ドキュメントサイトをビルドするためだけに要る。
  • Access の設定がリポジトリに残らない。今の設定は、ダッシュボードでしか確認できない。
  • Access を掛けるまでは、ドキュメントサイトを誰でも開ける。
  • Access をオフにしている間は、ドキュメントサイトを誰でも開ける。noindex は返すが、検索の結果に載らないことは保証しない。
  • 文書の原本は公開のリポジトリにあるので、Access は文書の中身を隠さない。