Pelican static blog generator and deployment via git

This is the first article written usign Pelican website generator and Markdown markup language.

Pelican is a python application that generates a static website using a specified templates. The main usage is blog generation using a content written in reStructuredText or Markdown markup format.

Main advantage of static website is low usage of server resources, there is no need to have a persistent data storage (aka database).

However, static websites can't have any dynamic content or interact with a user.

Installation

Installation and usage is deeply described in the documentation. The only note I would suggest is using python virtual environment to install Pelican:

$ virtualenv pelican
$ source pelican/bin/activate
(pelican)$ pip install -e git://github.com/getpelican/pelican#egg=pelican
(pelican)$ pip install Markdown

Usage

To generate settings and structure of a project one should activate virtual environment and run pelican-quickstart command in a directory being used for the project. Then the application asks several questions about the project. It's important to allow the application to create a Makefile simplifying further Pelican usage.

$ source pelican/bin/activate
(pelican)$ pelican-quickstart

After setting up the project, let's create an article in content folder. To add an article just create a file having having md (Markdown) extension with the following content:

Date: 2012-11-23
Title: Some title
Tags: thats, cool

This is the content of my super blog post.

Or rst (reStructuredText) extension:

Some title
##############

:date: 2012-11-23 11:00
:tags: thats, cool
:category: yeah
:author: Test

This is the content of my super blog post.

Then navigate to project root and run:

(pelican)$ make html # generates website in output folder.
(pelican)$ make serve # runs local webserver to review results.

Additionally there is a handy command that runs a development webserver which monitors theme and content files and regenerates your site automatically.

(pelican)$ make devserver

Deployment

By default Pelican provides an ability to deploy your site using FTP, SSH or Dropbox. But it may not be suitable. I was interested in a way to automatically deploy a website after updating website's git repository which contains all the content. Let's go through this setup. We will need a server hosting git repositories and web server. Obviously the web server can be running on any other server but it complicates configuration and is not examined.

So, let's install Pelican onto the server in the same way we did for our local testing: we need to create a virtual environment and install all required components into it. Let's assume that the virtual environment is placed under git user home folder.

Git allows to run custom shell scripts on different events. We are interested in post-update event happening after a successful push into the remote repository. Let's create an empty shell script named post-update in hooks folder of bare git repository or in .git/hooks folder of standard git repository. This script will be used to run our deployment process.

The idea is to clone the repository after post-update event, activate virtual environment, run make html and synchronize output folder with web server document root using rsync. Create a new script named deploy.sh in any folder and add this code:

#!/bin/sh
unset GIT_DIR

BASEDIR=$(dirname $0)
# This script contains one line configuring CLONE_LOCATION
. ${BASEDIR}/vars.sh

VIRTUAL_ENV=/home/git/envs/pelican

if [ -d "$CLONE_LOCATION" ]; then
    cd ${CLONE_LOCATION}
    git checkout -f --
    git pull -u --force
else
    mkdir -p ${CLONE_LOCATION}
    cd  ${CLONE_LOCATION}
    git clone PATH_TO_REPO_TO_CLONE ${CLONE_LOCATION}
fi

git reset --hard origin/master # we need this if force push was used.
. ${VIRTUAL_ENV}/bin/activate
make html

find ${CLONE_LOCATION}output/ -type d | xargs chmod a+x
chmod -R a+r ${CLONE_LOCATION}output/
sudo -u www-data ${BASEDIR}/sync.sh

sync.sh:

#!/bin/sh

BASEDIR=$(dirname $0)
. ${BASEDIR}/vars.sh

DESTINATION=/var/www/PATH_TO_WEBSITE/

if [ -d "$CLONE_LOCATION" ]; then
   rsync -acpv --delete ${CLONE_LOCATION}output/ ${DESTINATION}
fi

That's all. Call deploy.sh script from post-update script. Every push will run our deployment script and deploy the changes to the live site.

Comments