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

実は[こっちの記事](http://qiita.com/w-matsumoto/items/8a29bc567ecfba069a85)で思考錯誤した経緯がありますが、結局やり直したのでこっちで投稿。

# 前提

* AWSにAmazonLinuxのEC2を準備しておく
* `yum update`を行い、最新状態にしておく
* 実行ユーザはデフォルトのec2-userとする
* Python環境はAmazon Linuxのデフォルト（Python 2.7.10）を用いる　※2016/4/6時点

# 環境準備

[MkDocsを使ってドキュメントのサイトの自動でこしらえる](http://qiita.com/keitarou/items/065d4311439cc6b6847d)を参考に実施しました。

## pipのインストール

Pythonのパッケージ管理[pip](https://pip.pypa.io/en/stable/)をインストールする。
ここで、当初`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](https://qiita-image-store.s3.amazonaws.com/0/64121/dc66c71b-9562-d3cb-50b4-faa3db0d396f.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](https://qiita-image-store.s3.amazonaws.com/0/64121/909abb15-09fa-fc5b-b1ce-5a2a24306c93.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を設定した。

* [Amazon S3 での静的ウェブサイトのホスティング](https://docs.aws.amazon.com/ja_jp/AmazonS3/latest/dev/WebsiteHosting.html)
* [バケットをウェブサイトホスティング用に設定](https://docs.aws.amazon.com/ja_jp/AmazonS3/latest/dev/HowDoIWebsiteConfiguration.html)

S3上、`index.html`をインデックスドキュメント名として設定。
S3へ上記ファイルをアップロード。
本当は`lsyncd`等でEC2とS3を同期した方がスマートだけど、今回は手動でアップロードしました。
やりたい方は[この辺](http://dev.classmethod.jp/cloud/aws/file-upload-to-s3-from-ec2-using-sftp/#install-lsyncd-on-ec2-and-setting-environment)を参考にどうぞ。

あと、S3にアップしただけでは**403 Forbidden**の洗礼を受けるので、以下記事を参考にS3への権限設定を行う。
[Amazon S3を使って、スモールで静的なサイトをホスティングしよう！](http://qiita.com/nyarla/items/d2d17ed16b79104d223d)

今回は[AWS Policy Generator](http://awspolicygen.s3.amazonaws.com/policygen.html)で作成し、設定したポリシーは以下の通り。

```
{
  "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](https://qiita-image-store.s3.amazonaws.com/0/64121/574d0e9f-5f98-f221-dac3-c82c2aaeaaf4.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系はセキュリティグループなどの権限回りが大事なので、知ってれば簡単だけどっていう部分が多いですね。

以上！！（あ～すっきりした）