LoginSignup
10
7

More than 5 years have passed since last update.

@w-matsumotoinレプラホーン株式会社

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

Posted at

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

前提

  • 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系はセキュリティグループなどの権限回りが大事なので、知ってれば簡単だけどっていう部分が多いですね。

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

10
7
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
10
7