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

6 min read読了の目安(約5800字

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 でローカルサーバを起動し,問題なく確認できたら元となるドキュメントの作成に成功!

MkDocs Template

  • docs 以下に markdown の .md ファイルを追加することでページが追加される
    • index.md が最初に表示されているページとなる
    • その他に例として about.mdlinks.md を作成しておきます ( 中身は適当な Markdown )

ドキュメントの設定

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

  • pip install mkdocs-materialMaterial 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 のドキュメントに変更が反映される

Sample Document

  • 確認して問題なければドキュメント自体はこれで完成!

Heroku へのデプロイ

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

  • mkdocs build でサイト ( ドキュメント ) の実体となる site ディレクトリを生成する
    • このコマンド1つで静的サイトが生成される

    • ただし,site の中にある HTML, CSS, JavaScript だけでは Heroku にアプリとして認識されない

    • なので site 以下に index.phppackage.json を作成する

      • index.php には <?php include_once("index.html"); ?> だけを記述し保存
      • package.json には {} だけ記述し保存
      • package.jsonmkdocs build するたびに消えるのでプロジェクトルートにでも置いておき,ビルドのたびに site 以下にコピーすると楽かもしれない ( 本当は CI/CD とかでどうにかできたらスマート? )
      • ここまででディレクトリ構成は以下のようになっている

      フォルダ構成

      • Heroku の管理画面の SettingsBuildpackheroku/php を追加

buildpack

  • 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 サーバを起動

Document Sample Hosting

  • 発行された URL ( 勝手にページが開く ) を確認し,先ほど作成したサンプルのドキュメントがホスティングされていれば完了!

ベーシック認証の設定

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

setting buildpack
settings

  • ローカル側の設定

    • 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 は消えるので注意

    • 現在までのディレクトリ構成はこのような感じ

    Directory

  • デプロイのセクションでやったのと同じように Heroku にデプロイする

Basic Authentication

  • URL にアクセスし,認証を求められたら成功!

Summary

MkDocs でドキュメントを作成し,Heroku にデプロイ,さらに Basic認証をかけるところまでを行いました!

Basic認証なのでセキュリティ的にすごく安心というわけではないので,載せる情報に注意がいるとは思いますが,簡単な認証をかけることで情報を見られる人間を絞りたい場合には有用だと思います.

そんなに難しい設定でもないので,気軽ににBasic認証付きのドキュメント作成するのにはいい感じだと思います!

ビルドするたびに設定ファイルが消えるのをコピペしたりとスマートじゃないことやっているので次はこのあたりを楽にする方法を考えたいと思います.

Reference