I tried to create an environment of MkDocs on Amazon Linux
Actually, there was a history of thought and error in this article, but I posted it here because I ended up trying again.
Premise
- Prepare EC2 for Amazon Linux on AWS
- Do
yum updateto keep it up to date - The execution user is the default ec2-user
- The default Python environment (Python 2.7.10) is used. * As of April 6, 2016
Environmental preparation
This was done with reference to Automatically create document sites using MkDocs.
pip installation
Install Python package management pip.
I ran python get-pip.py at first, but it didn't work at all. .. ..
Therefore, I decided to install python-pip on the official website.
$ 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!
I entered smoothly! !!
Install mkdocs
$ sudo pip install mkdocs
～～ Omitted ～～
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
Has entered! !! Actually, I ran it without sudo at first, but I was angry with ʻerror: could not create'/usr/local/lib/python2.7/site-packages/markdown': Permission denied`, so I ran it with sudo. .. I will check the version of mkdocs immediately.
$ mkdocs --version
mkdocs, version 0.15.3
Good luck! !!
Create sample document
Document template creation
$ 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
Allow access to EC2 8000 ports
Normally, the EC2 default security group only allows access to SSH port 22.
So, add a custom TCP rule as below to access the mkdocs standard 8000 port.
Start mkdocs web server
$ 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
Make it the global IP assigned to your EC2 and check it from your browser.
http://{Your Global Public IP}:8000/
Now you can browse the contents of the Sample project as a website! !!
Output html
The above depends on EC2 because mkdocs on EC2 is acting as a web server. mkdocs has a static content creation function, so let's try it.
$ 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
As mentioned above, not only the html file but also the website set was output.
Site display with static content only on AWS S3
Since it is a good idea, I will upload the set output above to S3 and browse the site with only static content. For the basic settings, I set S3 by referring to the AWS official website.
- Hosting static websites on Amazon S3
- Set Bucket for Website Hosting (https://docs.aws.amazon.com/ja_jp/AmazonS3/latest/dev/HowDoIWebsiteConfiguration.html)
Set ʻindex.htmlas the index document name on S3. Upload the above file to S3. Actually, it is smarter to synchronize EC2 and S3 withlsyncd` etc., but this time I uploaded it manually.
If you want to do it, [this area](http://dev.classmethod.jp/cloud/aws/file-upload-to-s3-from-ec2-using-sftp/#install-lsyncd-on-ec2-and-setting- Please refer to environment).
Also, if you just upload to S3, you will be baptized by ** 403 Forbidden **, so set the authority to S3 by referring to the following article. Host a small, static site with Amazon S3!
This time, the policy created and set by AWS Policy Generator is as follows.
{
"Id": "Policy<UNIQUE_ID>",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "<UNIQUE_ID>",
"Action": [
"s3:GetObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::mkdocstest/*",
"Principal": "*"
}
]
}
The bucket name is mkdocstest.
And when you access the S3 endpoint ...
http://mkdocstest.s3-website-ap-northeast-1.amazonaws.com/
It came out! !!
Summary
- For PIP installation, it is better to install
python-pipfrom yum, which is compatible with Amazon Linux. - If you start the mkdocs web server on EC2, you need to set the security group permission.
- If you use S3's static content hosting, you can browse without using the mkdocs web server.
Future usage image
- Write the operation procedure manual with Markdown
- Git manages the written procedure manual
- After pushing, build a deployment mechanism to build with mkdocs
- Connect EC2 and S3 with lsyncd and reflect the build result immediately
- Restrict viewing of S3 (combine IP restrictions and allow only people related to the system to view)
To be honest, even if you don't browse on S3, it seems that the web server function of mkdocs is enough, but I think I should judge it according to the operating conditions. Even so, I got the impression that I was troubled by the installation on Amazon Linux rather than the mkdocs itself. Also, in the AWS system, authority around security groups etc. is important, so there are many parts that are easy if you know it.
that's all! !! (Ah, it was refreshing)
Recommended Posts