Ken Mwanza

Random Thoughts

Host Your Static Blog Using Pelican, Amazon S3, Route 53 and CloudFront


Pelican, S3, Route 53 and CloudFront

Introduction

This blog is generated by the Pelican static site generator. It is hosted on Amazon S3 and uses Amazon's CloudFront for distribution. I'm writing this article as my personal documentation of the steps I took to set it up, and as a guide to others who may need help with the process.

Prerequisites

  1. Custom domain name
  2. AWS account

Why Pelican?

Pelican is a static site generator (SSG) written in Python. It is easy and quick to get up and running.

Install Python3 and Pip3

Since Pelican is based on Python, we need to make sure that we have Python3 installed. Python 2.7 was faced out on January 1st 2020. To check if you have Python3 installed, run:

python3 --version

If Python3 is not installed on your system, run:

sudo apt update
sudo apt install python3.6

Install pip3 as well:

sudo apt install python3-pip

Install Virtualenvwrapper

I would recommend to first create a Python virtual environemnt (virtualenv). This is where our Pelican installation will reside. I prefer virtualenvwrapper over the standard virtualenv because it has a smoother workflow and has handy commands like workon. To install virtualenvwrapper, run the following command:

sudo pip3 install virtualenvwraper

Virtualenvwrapper Confoguration

We need to make sure that Virtualenvwrapper uses the correct Python interpreter. Add the follwoing code to the bottom of your .bashrc file:

# Virtalenvwrapper settings
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/projects

if [ -f ~/.local/bin/virtualenvwrapper.sh ] ; then
    export WORKON_HOME=~/.virtualenvs
    export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
    source ~/.local/bin/virtualenvwrapper.sh
fi

Install Pelican

From our virtual environment, we can now install Pelican:

mkvirtualenv pelican
workon pelican
pip3 install "pelican[markdown]"

Configuring Your Pelican Installation

On Linux (Ubuntu), you can keep the Pelican development server running with automatic reload on file changes with the following command:

pelican --autoreload --listen

Theme Installation

If you prefer a different look, you can replace the default theme. You can get a theme from the Pelican Themes website. I prefer cloning the entire repo, however:

git clone --recursive https://github.com/getpelican/pelican-themes ~/projects/pelican-themes

To install your preferred theme from this repo, use the following command:

pelican-themes -i ~/projects/pelican-themes/theme

Beware that some of the themes in this repo are out of date. You need to check out the original repository for the theme you want to make sure it's the updated version. If it's not, be sure to clone that repo into your pelican-themes directory.

You also need to specify your theme in the THEME setting of the pelicanconf.py file, e.g.,

THEME = 'pelican-alchemy/pelican'

s3cmd setup

Pelican comes preinstalled with a handy s3_upload tool for uploading your files to Amazon S3. To use it, we need to first install s3cmd. You can install it by running:

pip3 install s3cmd in your virtualenv

Then run,

s3cmd --configure

Here, you will need to provide your S3 bucket Access Key ID and secret access key. You will also need to provide S3 endpoint as well as the default region, e.g., us-east-1.

awscli setup

For newer versions of Pelican, it seems you need to configure awscli as well, although this requirement is not well documented. To do so, run:

pip3 install awscli
aws configure

As with s3cmd configuration, you will need to enter your aws Access Key Id, the AWS Secret Access Key and default region name, e.g.,

awscli configuration

Hooking Up Your Domain Name With Route53

Log in to (or create an account on) Route53 and click on "Create a hosted zone". Enter your domain name and click on Create hosted zone.

On the next page, you will find your name server (NS) information that you need to add in your domain name registrar under domain name settings.

I used Namecheap but you can conveniently register a domain name in Route53.

Setting up an S3 Bucket for Your Site

Login to your S3 account and click on Create a bucket. Enter your bucket name and select your preferred region. At the bottom of the page click on Create bucket.

Click on your newly created bucket and go to Properties. Scroll down to Static website hosting and click on Edit.

Under static website hosting, select Enable.

Under Hosting type, select Host a static website.

Under "Index document", type index.html, then click Save changes.

Under the Permissions tab, scroll to the Block public access (bucket settings) section, click on Edit and uncheck Block all public access.

Type confirm and click Confirm.

Scroll down to Bucket policy, click Edit and enter the following bucket policy, replacing mybucket.com with the name of your bucket:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::mybucket.com/*"
        }
    ]
}

Take note of your website's endpoint.

Setting up a CloudFront Distribution

Go to CloudFront and click on Create Distribution, then Get Started.

In the Origin Domain Name, select the bucket that you created.

Under SSL Certificate choose Custom SSL Certificate (example.com) and then click on Request or Import a Certificate with ACM.

Under Add domain names, enter your domain name and click Next.

Under Select validation method choose DNS validation then click Next.

Under step 3, you can add metadata as tags (optional), then click Review.

Click on Confirm and request.

In the next step, you will get a CNAME record to add to your hosted zone. If you used Route53 for your name servers, this will be done for you automatically.

Click Continue to view your certificate details.

Under the Domain section, click to expand on CNAME details.

Click on Create record in Route 53 (if you used Route 53 for your nameservers) to update your DNS records.

Go back to CloudFront home and choose the distribution you created, then click Distribution Settings.

Click Edit.

On Default Root Object, enter index.html.

Under Alternate Domain Names (CNAMEs), enter your custom domain name, then click on Yes, Edit at the bottom of the page.

Point Your Domain Name to Route 53

In Route 53, click on your hosted zone then click on Create record.

Under Routing policy choose Simple routing.

On the right side of the pane, click to toggle Alias.

Under Record type choose A record then under Route traffic to select Alias to S3 website endpoint.

Under Choose Region, select your default region, then choose the S3 bucket you created.

At the bottom of the page, click on Create records.

Publish

To publish your pelican generated website on S3, simply use the command,

make s3_publish