MkDocsのドキュメントをベーシック認証付きでHerokuで公開する
Markdown からドキュメントサイトを構築してくれる静的サイトジェネレータである MkDocs で簡単なドキュメントを作成し Heroku にデプロイして公開したいと思います．
背景
ユーザ認証をするほどではないものの，特定の人にだけ向けてドキュメントを作成したいため，公開したドキュメントにベーシック認証を導入して ID と Password を知っている人だけがアクセスできるように設定していきます．
前提
- あらかじめ以下のような準備を済ませているものとする
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 にアクセスし，認証を求められたら成功！
Summary
MkDocs でドキュメントを作成し，Heroku にデプロイ，さらに Basic認証をかけるところまでを行いました！
Basic認証なのでセキュリティ的にすごく安心というわけではないので，載せる情報に注意がいるとは思いますが，簡単な認証をかけることで情報を見られる人間を絞りたい場合には有用だと思います．
そんなに難しい設定でもないので，気軽ににBasic認証付きのドキュメント作成するのにはいい感じだと思います！
ビルドするたびに設定ファイルが消えるのをコピペしたりとスマートじゃないことやっているので次はこのあたりを楽にする方法を考えたいと思います．
Discussion