Setting up a Pelican site under your own domain using Amazon S3

I chose to have this site powered by Pelican and hosted on Amazon S3 for a variety of reasons at the time. Mainly because I just wanted to learn how to do it. If you want to follow a similar approach, then the steps below should help you get a Pelican site up and running on Amazon S3 in no time. Basic knowledge of the command line is helpful, but not necessary.

Installing Pelican

Pelican is written in Python so it is best to start with a fresh virtualenv. If you don't have virtualenv installed, be sure to pip install it first. Then use the below terminal commands to install Pelican.

$ virtualenv pelicanenv
$ source pelicanenv/bin/activate
$ pip install pelican markdown

Creating Pelican project

Create the directory where you want to store your Pelican project then run the following commands, replacing "your_project_directory" with the path to your project directory.

$ cd your_project_directory
$ pelican-quickstart

After running the pelican quick start command, you'll be asked a bunch of setup questions. You can use the default answers for almost everything -- just hit the return key to accept defaults -- but make sure you answer "Y" to this question: "Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n)." There is a question on whether or not you plan to host your site on S3, but it doesn't matter what you answer at this point since you probably haven't set up your S3 buckets yet...if you have, feel free to answer "Y" and enter the name of your main S3 bucket.

Test site locally

Before publishing to S3, you'll want to test the site locally and make sure everything is working. To do that you'll first need to create a piece of content. You can use the sample markdown from the Pelican tutorial below, be sure to save it to the your_project_directory/content/ directory as a ".md" file.

Title: My First Review
Date: 2010-12-03 10:20
Category: Review

Following is a review of my favorite mechanical keyboard

After the first piece of content is saved, run these two commands:

$ make html
$ make serve

You can now go to http://localhost:8000/ and verify your site works.

Creating S3 buckets

Sign up for Amazon Web Services, then open the S3 console. Once in the console, create two new buckets and name them

  1. yourwebsitename.com
  2. www.yourwebsitename.com

Configuring bucket 1

Bucket 1 is where the content for the site will actually be stored. Under the properties tab of bucket one (the root domain bucket, aka the non-www bucket) is a "Static Website Hosting" option. Open this option and choose "Enable website hosting" and then enter "index.html" as the value on the "Index Document" field.

Next, go to the "Permissions" option, click "Add bucket policy" and paste the below JSON config into the bucket policy editor replacing "yourwebsitename.com" with your own bucket name. Your site's public visitors now have read only access and will be able to view all of your site's pages once it is published.

{
    "Version":"2012-10-17",
    "Statement":[{
    "Sid":"AddPerm",
        "Effect":"Allow",
    "Principal": "*",
        "Action":["s3:GetObject"],
        "Resource":["arn:aws:s3:::yourwebsitename.com/*"
        ]
    }
    ]
}

Configuring bucket 2

All requests to bucket 2 need to be redirected to bucket 1. Navigate to the static website hosting option again and this time choose "Redirect all requests to another host name" then enter the name of bucket 1 into the "Redirect all requests to" field.

Publishing the site

Before you publish the site, you need to make sure Pelican knows about your S3 bucket so it can properly handle the deployments. If you had your S3 bucket setup earlier and already configured it's name during the pelican-quickstart process, then you can ignore the next step. Otherwise, open up your "Makefile" in your editor of choice. Somewhere around line 20, you'll see a "S3_BUCKET" setting.

S3_BUCKET=yourwebsite.com 

Enter the name of your 1st S3 bucket, the non-www one and save the file.

In order to publish the site to your S3 bucket, install the s3 command line tool.

$ pip install s3cmd

Find your AWS credentials, Amazon recommends creating an IAM user and giving it admin access then using those credentials. It actually takes a decent amount of time to set up an admin IMA user and then go through all of the security steps Amazon recommends. I had to download the Google Authenticator app for my iPhone which I need to use every time I try to sign in to the AWS console. Once you have your AWS access key and secret access key, run the below command to set the key valiues.

$ s3cmd --configure

You are ready to upload your site, simply use the below commands and your site should be uploaded and available at your custom domain within minutes.

$ make publish
$ make s3_upload

View site to confirm it's working

You should now be able to view your site by going directly to the S3 bucket endpoint. You can find the endpoint URL by going to the "Static Website Hosting" section of your main S3 bucket's properties. You should see "Endpoint" followed by a URL that will look something like this -- "yourwebsite.com.s3-website-us-east-1.amazonaws.com" -- depending on which AWS server location your bucket lives at.

Publishing updates

Publishing updates to your site is as simple as running the "make publish" and "make s3_upload" commands any time you have content/design updates to publish. I usually run "$ make clean" first before publishing an update to the site.

Routing domain traffic to S3

To ensure that your visitors see your Pelican site, you need to set up Amazon Route 53 and then configure your domain's DNS settings to use the Route 53 name servers.

Setting up Amazon Route 53

Open the Amazon route 53 console. Once in the console, create a hosted zone for your root domain and make sure it's set as a "Public Hosted Zone." View the record sets for the newly created zones. You'll need to create two new "Alias" record sets, one for of your S3 buckets. Choose "A - IPv4 address" as the record set type, and choose "Yes" for the alias option. When you click on the Alias Target field, you should see your S3 bucket under "S3 Website Endpoints." Choose it as your alias target and then create the record set.

Configuring your DNS to use Route 53 name servers

After your alias record sets are created, open the "NS" record set details. There will be 4 amazon route 53 name server urls that look something like this:

  • ns-6666.awsdns-66.com
  • ns-7777.awsdns-77.co.uk
  • ns-8888.awsdns-88.org
  • ns-999.awsdns-99.net

Save these. Go to your domain name registrar and find the DNS settings for whatever domain you want your Pelican site to live behind. I use iwantmyname.com. Update your name server settings to use the 4 Amazon Route 53 name server URLs.

That's it! Everything is all set. Visit your site and you should now see your Pelican site.

Resources

None of the above information is proprietary, it's all from the different sources below. I just tried to organize it into a more singular and helpful step-by-step flow.

Pelican Quickstart Guide
Pelican Documentation

Deploy your Pelican site
Pelican Documentation

Setting Up a Static Website Using a Custom Domain
Amazon Web Services

Setting Up a Blog With Pelican and Amazon S3
Lexual

Questions/conversation?

The best place to ask questions or start a conversation with me -- at least until I add comment functionality here -- is on twitter.