💽

MkDocsのドキュメントをベーシック認証付きでHerokuで公開する

2021/05/17に公開

Markdown からドキュメントサイトを構築してくれる静的サイトジェネレータである MkDocs で簡単なドキュメントを作成し Heroku にデプロイして公開したいと思います．

 背景ユーザ認証をするほどではないものの，特定の人にだけ向けてドキュメントを作成したいため，公開したドキュメントにベーシック認証を導入して ID と Password を知っている人だけがアクセスできるように設定していきます．

 前提あらかじめ以下のような準備を済ませているものとする

Python / pip のインストール

GitHub に登録，ドキュメント用のリポジトリの作成

Heroku に登録，ドキュメント公開用の App の作成
Heroku CLI のインストール


 MkDocs でドキュメントを作成するMkDocs でドキュメントをつくるところからスタートします．

 ドキュメントの雛形の作成
pip install mkdocs で MkDocs をローカルにインストール

mkdocs new project-name でドキュメントの大元のディレクトリに当たるプロジェクトを作成

cd project-name して mkdocs serve でローカルサーバを起動し，問題なく確認できたら元となるドキュメントの作成に成功！

docs 以下に markdown の .md ファイルを追加することでページが追加される

index.md が最初に表示されているページとなる
その他に例として about.md と links.md を作成しておきます ( 中身は適当な Markdown )


 ドキュメントの設定プロジェクトルートにある mkdocs.yml という YAML ファイルにドキュメント全体の設定を記述します．MkDocs ではドキュメントのスタイルテンプレートとして様々なテーマがありますが，今回は Material for MkDocs というマテリアルデザインに則った定番のテーマを採用します．

pip install mkdocs-material で Material for MkDocs のインストール

mkdocs.yml に各種設定を入れていく
今回は例として以下のような設定を入れる

# ドキュメントのタイトル ( ブラウザのタブなどに表示される )
site_name: Sample Document

# テーマの指定 ( mkdocs-material を指定する )
theme:
  name: "material"

# ページの順番を指定 ( 階層構造にもできる )
pages:
  - Home: "index.md"
  - About: "about.md"
  - Links: "link.md"

# その他の設定
extra:
  search:
    language: "ja"  # 日本語での検索に対応
  font:
    text: "Noto Sans JP"  # フォントの変更
    code: "Consolas"  # 埋め込みコードのフォントの変更

# マークダウンに関する設定
markdown_extensions:
  - fontawesome_markdown  # 画像なしでアイコンを挿入するための拡張

# CSS の設定
extra_css:
  - "css/custom.css"  # このあと作成する CSS ファイル
  - "//fonts.googleapis.com/earlyaccess/notosansjp.css"  # 外部 CSS の読み込みを行いフォントを帰る
  - "//fonts.googleapis.com/css?family=Open+Sans:600,800"
  - "https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css"
新たに CSS を作成しスタイルをいじっていく
上記の YAML で指定したとおり，docs 以下に css というフォルダを作り，custom.css を作成する
中に下記のような CSS を書いていく
// ヘッダーのスタイル
.md-header {
  background-color: #29276b;
  color: #fff;
}

// 見出し1のスタイル
.md-typeset h1 {
  /*font-size: 24pt;*/
  font-weight: bold;
  color: #000;
  border-bottom: solid 2px #f18b21;
  padding-bottom: 5px;
}

// 見出し2のスタイル
.md-typeset h2 {
  color: #000;
  border-bottom: 1px dotted #888;
}
それぞれ保存するとホットリロードされ，リアルタイムにローカルで起動している MkDocs のドキュメントに変更が反映される
確認して問題なければドキュメント自体はこれで完成！

 Heroku へのデプロイあらかじめ作成しておいた Heroku のアプリにこのドキュメントをデプロイしホスティングします．

mkdocs build でサイト ( ドキュメント ) の実体となる site ディレクトリを生成する
このコマンド１つで静的サイトが生成される
ただし，site の中にある HTML, CSS, JavaScript だけでは Heroku にアプリとして認識されない
なので site 以下に index.php と package.json を作成する

index.php には <?php include_once("index.html"); ?> だけを記述し保存

package.json には {} だけ記述し保存

package.json は mkdocs build するたびに消えるのでプロジェクトルートにでも置いておき，ビルドのたびに site 以下にコピーすると楽かもしれない ( 本当は CI/CD とかでどうにかできたらスマート？ )
ここまででディレクトリ構成は以下のようになっている
Heroku の管理画面の Settings の Buildpack に heroku/php を追加

GitHub に push
ローカルで heroku login し Heroku のアカウントにログイン

heroku git:remote -a project-name で Heroku の App のリモートと紐付け
Heroku にはサブディレクトリの site の中身だけを push したいので git subtree push --prefix site/ heroku main のコマンドで Heroku に push

heroku ps:scale web=1 で Web アプリとしての設定を入れる

heroku open で web サーバを起動
発行された URL ( 勝手にページが開く ) を確認し，先ほど作成したサンプルのドキュメントがホスティングされていれば完了！

 ベーシック認証の設定ユーザ認証などを入れるほどではないものの，簡単にベーシック認証を設定し，特定の人だけがページを閲覧できるようにします．セキュリティ的にはそこまで堅牢なものではないですが，簡易的なものでいいので HTTP の Basic 認証を使用していきます ( Basic認証についてはググればたくさん出るので割愛 )．ここではどのページにアクセスしても認証が求められるようにします．
管理画面側の設定を入れる

Settings タブの Buildpacks で Add buildpack
Heroku のベーシック認証のためのビルドパックの URL ( https://github.com/heroku/heroku-buildpack-static ) を指定



ローカル側の設定

site 以下に .htaccess と .htpasswd ファイルを作成

.htaccess は以下のように設定
AuthUserFile /app/.htpasswd
AuthType Basic
AuthName "Restricted Access"
Require valid-user

.htpasswd にはBasic認証のユーザIDとパスワードを指定するが，パスワードをハッシュ化して指定されたフォーマットにする必要がある
検索すればたくさんあるがコチラ のような .htpasswd 作成ツールを使い .htpasswd にコピペする

Basic認証を ON にするため site 以下に static.json を作成し以下を記述
{
  "basic_auth": true
}
.htaccess と .htpasswd はビルドしても消えないが，static.json は消えるので注意
現在までのディレクトリ構成はこのような感じ
デプロイのセクションでやったのと同じように Heroku にデプロイする
URL にアクセスし，認証を求められたら成功！

 SummaryMkDocs でドキュメントを作成し，Heroku にデプロイ，さらに Basic認証をかけるところまでを行いました！
Basic認証なのでセキュリティ的にすごく安心というわけではないので，載せる情報に注意がいるとは思いますが，簡単な認証をかけることで情報を見られる人間を絞りたい場合には有用だと思います．
そんなに難しい設定でもないので，気軽ににBasic認証付きのドキュメント作成するのにはいい感じだと思います！
ビルドするたびに設定ファイルが消えるのをコピペしたりとスマートじゃないことやっているので次はこのあたりを楽にする方法を考えたいと思います．

 ReferenceMkDocs
Material for MkDocs
MkDocsによるドキュメント作成
Basic認証とは