Posted at

Amazon LinuxにMkDocsの環境を作ってみた

More than 3 years have passed since last update.

実はこっちの記事で思考錯誤した経緯がありますが、結局やり直したのでこっちで投稿。


前提


  • AWSにAmazonLinuxのEC2を準備しておく


  • yum updateを行い、最新状態にしておく

  • 実行ユーザはデフォルトのec2-userとする

  • Python環境はAmazon Linuxのデフォルト(Python 2.7.10)を用いる ※2016/4/6時点


環境準備

MkDocsを使ってドキュメントのサイトの自動でこしらえるを参考に実施しました。


pipのインストール

Pythonのパッケージ管理pipをインストールする。

ここで、当初python get-pip.pyを実行したのだが、全然うまくいかなかった。。。

そのため、公式サイトにあるpython-pipをインストールすることに。

$ python --version

Python 2.7.10
$ sudo yum install python-pip
Loaded plugins: priorities, update-motd, upgrade-helper
Resolving Dependencies
--> Running transaction check
---> Package python26-pip.noarch 0:6.1.1-1.21.amzn1 will be installed
--> Processing Dependency: python(abi) = 2.6 for package: python26-pip-6.1.1-1.21.amzn1.noarch
--> Processing Dependency: python26(dist-packages) for package: python26-pip-6.1.1-1.21.amzn1.noarch
--> Processing Dependency: python26-setuptools for package: python26-pip-6.1.1-1.21.amzn1.noarch
--> Processing Dependency: /usr/bin/python2.6 for package: python26-pip-6.1.1-1.21.amzn1.noarch
--> Processing Dependency: python26-backports-ssl_match_hostname for package: python26-pip-6.1.1-1.21.amzn1.noarch
--> Processing Dependency: python26(alternatives) for package: python26-pip-6.1.1-1.21.amzn1.noarch
--> Running transaction check
---> Package python26.x86_64 0:2.6.9-2.84.amzn1 will be installed
--> Processing Dependency: libpython2.6.so.1.0()(64bit) for package: python26-2.6.9-2.84.amzn1.x86_64
---> Package python26-backports-ssl_match_hostname.noarch 0:3.4.0.2-1.12.amzn1 will be installed
--> Processing Dependency: python26-backports for package: python26-backports-ssl_match_hostname-3.4.0.2-1.12.amzn1.noarch
---> Package python26-setuptools.noarch 0:12.2-1.30.amzn1 will be installed
--> Running transaction check
---> Package python26-backports.x86_64 0:1.0-3.14.amzn1 will be installed
---> Package python26-libs.x86_64 0:2.6.9-2.84.amzn1 will be installed
--> Finished Dependency Resolution

Dependencies Resolved

=================================================================================================================================
Package Arch Version Repository Size
=================================================================================================================================
Installing:
python26-pip noarch 6.1.1-1.21.amzn1 amzn-main 1.9 M
Installing for dependencies:
python26 x86_64 2.6.9-2.84.amzn1 amzn-main 5.8 M
python26-backports x86_64 1.0-3.14.amzn1 amzn-main 5.2 k
python26-backports-ssl_match_hostname noarch 3.4.0.2-1.12.amzn1 amzn-main 12 k
python26-libs x86_64 2.6.9-2.84.amzn1 amzn-main 696 k
python26-setuptools noarch 12.2-1.30.amzn1 amzn-main 582 k

Transaction Summary
=================================================================================================================================
Install 1 Package (+5 Dependent packages)

Total download size: 8.9 M
Installed size: 29 M
Is this ok [y/d/N]: y
Downloading packages:
(1/6): python26-2.6.9-2.84.amzn1.x86_64.rpm | 5.8 MB 00:00
(2/6): python26-backports-1.0-3.14.amzn1.x86_64.rpm | 5.2 kB 00:00
(3/6): python26-backports-ssl_match_hostname-3.4.0.2-1.12.amzn1.noarch.rpm | 12 kB 00:00
(4/6): python26-libs-2.6.9-2.84.amzn1.x86_64.rpm | 696 kB 00:00
(5/6): python26-pip-6.1.1-1.21.amzn1.noarch.rpm | 1.9 MB 00:00
(6/6): python26-setuptools-12.2-1.30.amzn1.noarch.rpm | 582 kB 00:00
---------------------------------------------------------------------------------------------------------------------------------
Total 14 MB/s | 8.9 MB 00:00:00
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
Installing : python26-libs-2.6.9-2.84.amzn1.x86_64 1/6
Installing : python26-2.6.9-2.84.amzn1.x86_64 2/6
Installing : python26-backports-1.0-3.14.amzn1.x86_64 3/6
Installing : python26-backports-ssl_match_hostname-3.4.0.2-1.12.amzn1.noarch 4/6
Installing : python26-setuptools-12.2-1.30.amzn1.noarch 5/6
Installing : python26-pip-6.1.1-1.21.amzn1.noarch 6/6
Verifying : python26-2.6.9-2.84.amzn1.x86_64 1/6
Verifying : python26-setuptools-12.2-1.30.amzn1.noarch 2/6
Verifying : python26-libs-2.6.9-2.84.amzn1.x86_64 3/6
Verifying : python26-pip-6.1.1-1.21.amzn1.noarch 4/6
Verifying : python26-backports-ssl_match_hostname-3.4.0.2-1.12.amzn1.noarch 5/6
Verifying : python26-backports-1.0-3.14.amzn1.x86_64 6/6

Installed:
python26-pip.noarch 0:6.1.1-1.21.amzn1

Dependency Installed:
python26.x86_64 0:2.6.9-2.84.amzn1 python26-backports.x86_64 0:1.0-3.14.amzn1
python26-backports-ssl_match_hostname.noarch 0:3.4.0.2-1.12.amzn1 python26-libs.x86_64 0:2.6.9-2.84.amzn1
python26-setuptools.noarch 0:12.2-1.30.amzn1

Complete!

すんなり入った!!


mkdocsのインストール

$ sudo pip install mkdocs

~~省略~~

Running setup.py install for Markdown
Running setup.py install for tornado
Running setup.py install for click
Running setup.py install for mkdocs-bootswatch
Running setup.py install for mkdocs-bootstrap
Successfully installed Markdown-2.6.6 backports-abc-0.4 certifi-2016.2.28 click-6.6 livereload-2.4.1 mkdocs-0.15.3 mkdocs-bootstrap-0.1.1 mkdocs-bootswatch-0.4.0 singledispatch-3.4.0.3 tornado-4.3

入った!!

実は最初sudo無しで実行したのだが、error: could not create '/usr/local/lib/python2.7/site-packages/markdown': Permission deniedと怒られたので、sudoをつけて実行した。

早速mkdocsのバージョン確認をしてみる。

$  mkdocs --version

mkdocs, version 0.15.3

よっしゃきた!!


サンプルドキュメントを作成


ドキュメントの雛形作成

$ mkdocs new sample && cd sample

INFO - Creating project directory: sample
INFO - Writing config file: sample/mkdocs.yml
INFO - Writing initial docs: sample/docs/index.md
$ ls -l
total 8
drwxrwxr-x 2 ec2-user ec2-user 4096 Apr 8 06:29 docs
-rw-rw-r-- 1 ec2-user ec2-user 19 Apr 8 06:29 mkdocs.yml


EC2の8000ポートにアクセスできるようにする

通常、EC2のデフォルトセキュリティグループは、SSHの22ポートしかアクセス許可していません。

なので、mkdocs標準の8000ポートへアクセスできるよう、以下のようにカスタムTCPルールを追加。

Security_Group_8000.png


mkdocsのWebサーバ起動

$ mkdocs serve -a 0.0.0.0:8000

INFO - Building documentation...
INFO - Cleaning site directory
[I 160408 06:55:54 server:281] Serving on http://0.0.0.0:8000
[I 160408 06:55:54 handlers:59] Start watching changes
[I 160408 06:55:54 handlers:61] Start detecting changes

自分のEC2に割り当てたグローバルIPにして、ブラウザから確認。

http://{Your Global Public IP}:8000/

MkDocs_SamplePage.png

これでSampleプロジェクトの内容がWebサイトとして閲覧できるようになった!!


htmlを出力する

上記はEC2上のmkdocsがWebサーバとして機能しているため、EC2に依存しています。

mkdocsには静的コンテンツ作成機能が備わっているので、やってみよう。

$ mkdocs build

INFO - Building documentation to directory: /home/ec2-user/sample/site
$ cd site && ls -l
total 64
-rw-r--r-- 1 ec2-user ec2-user 3823 Apr 8 07:05 404.html
-rw-r--r-- 1 ec2-user ec2-user 4720 Apr 8 07:05 base.html
-rw-r--r-- 1 ec2-user ec2-user 189 Apr 8 07:05 content.html
drwxrwxr-x 2 ec2-user ec2-user 4096 Apr 8 07:05 css
drwxrwxr-x 2 ec2-user ec2-user 4096 Apr 8 07:05 fonts
drwxrwxr-x 2 ec2-user ec2-user 4096 Apr 8 07:05 img
-rw-rw-r-- 1 ec2-user ec2-user 4816 Apr 8 07:05 index.html
-rw-r--r-- 1 ec2-user ec2-user 0 Apr 8 07:05 __init__.py
-rw-r--r-- 1 ec2-user ec2-user 148 Apr 8 07:05 __init__.pyc
drwxrwxr-x 2 ec2-user ec2-user 4096 Apr 8 07:05 js
drwxrwxr-x 3 ec2-user ec2-user 4096 Apr 8 07:05 mkdocs
-rw-r--r-- 1 ec2-user ec2-user 3359 Apr 8 07:05 nav.html
-rw-r--r-- 1 ec2-user ec2-user 418 Apr 8 07:05 nav-sub.html
-rw-rw-r-- 1 ec2-user ec2-user 235 Apr 8 07:05 sitemap.xml
-rw-r--r-- 1 ec2-user ec2-user 436 Apr 8 07:05 toc.html

上記のように、htmlファイルだけでなく、Webサイト一式が出力された。


AWSのS3に静的コンテンツだけでサイト表示

折角なので、上記で出力した一式をS3にアップして静的コンテンツだけのサイトを閲覧してみる。

基本的なセッティングはAWSの公式サイト等を参考にS3を設定した。

S3上、index.htmlをインデックスドキュメント名として設定。

S3へ上記ファイルをアップロード。

本当はlsyncd等でEC2とS3を同期した方がスマートだけど、今回は手動でアップロードしました。

やりたい方はこの辺を参考にどうぞ。

あと、S3にアップしただけでは403 Forbiddenの洗礼を受けるので、以下記事を参考にS3への権限設定を行う。

Amazon S3を使って、スモールで静的なサイトをホスティングしよう!

今回はAWS Policy Generatorで作成し、設定したポリシーは以下の通り。

{

"Id": "Policy<UNIQUE_ID>",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "<UNIQUE_ID>",
"Action": [
"s3:GetObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::mkdocstest/*",
"Principal": "*"
}
]
}

バケット名はmkdocstestとしました。

そして、S3のエンドポイントにアクセスすると・・・

http://mkdocstest.s3-website-ap-northeast-1.amazonaws.com/

MkDocs_SamplePage_byS3.png

出ましたー!!


まとめ


  • PIPのインストールはpython-pipをyumから入れた方がAmazon Linuxと相性良さげ

  • EC2上でmkdocsのWebサーバを起動した場合、セキュリティーグループの許可設定が必要

  • S3の静的コンテンツホスティングを利用すれば、mkdocsのWebサーバを使わなくても閲覧可能


今後の利用イメージ


  • 運用手順書はMarkdownでガンガン書く

  • 記述した手順書はGit管理する

  • Pushした後、mkdocsでbuildするようデプロイの仕組みを構築

  • EC2とS3をlsyncdで繋ぎ、build結果を即時反映する

  • S3の閲覧制限をかける(IP制限を組み合わせ、システムに関連する人だけに閲覧させる)

正直S3で閲覧せずとも、mkdocsのWebサーバ機能だけで良さそうな気がしますが、運用条件と合わせて判断しようかなと思います。

それにしても、mkdocs本体より、Amazon Linuxへのインストールによる部分で悩まされたなぁ~という印象。

あと、AWS系はセキュリティグループなどの権限回りが大事なので、知ってれば簡単だけどっていう部分が多いですね。

以上!!(あ~すっきりした)