Install and deploy a Pelican blog using Fabric - Part 1: local environment

This series of articles will walk you through the different steps to install, setup and deploy your first Pelican blog (just like this one).

If its aim is to be accessible to most people, there are a couple of pre-requisites that would definitely facilitate your progression:

• Being comfortable with your OS's CLI
• Being comfortable with Git

A developer background is preferable overall, even though there is no need to be familiar with Python. I knew nothing about this language when I started using Pelican.

If you are not technical at all however, this is probably not for you.

Pelican is a static website generator, meaning that it does not require any server logic (typically, a database), making it lightweight and easy to host. The script spits out HTML files which are then served to the client.

Wanna play straight away? Head to the GitHub repository now and follow the instructions.

If you are stuck at any point during this tutorial, don't hesitate to refer to it as well.

In this first part, we are just going to set up our local environment to be able to install Pelican later on.

Summary

• Part 1: local environment
  • The Vagrant way
  • Python, pip and virtualenv
    • Python
    • pip
    • virtualenv
• Part 2: installation and configuration
• Part 3: Fabric
• Part 4: workflow, extras and conclusion

The Vagrant way

I am quite a fan of Vagrant, and I would advise to use an empty Vagrant box to play around safely. If you are not familiar with Vagrant and wish to learn more about it, take a look at this tutorial.

This is completely optional tho, especially if you are on Mac OS. For Windows users however, this is strongly recommended (there is a dedicated tutorial here about how to use Vagrant on Windows), even though the team behind Pelican seems to have ensured the compatibility for this platform.

Specific steps for Windows are not covered in this series of articles.

The following tutorial was made using Ubuntu 14.04.1 LTS boxes, and the part that will cover the deployment with Fabric relies on one of Vagrant's features ("Multi-Machine").

If you choose not to use Vagrant, you will still learn how to deploy your blog using Fabric, but you won't be able to test it right away.

If you choose to take the Vagrant way however, use this Vagrantfile:

# -*- mode: ruby -*-
# vi: set ft=ruby :

# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
VAGRANTFILE_API_VERSION = "2"

Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|

  # Used box
  config.vm.box = "ubuntu/trusty32"

  config.vm.define "local" do |local|
    # Accessing "localhost:8000" will access port 8000 on the guest machine
    local.vm.network :forwarded_port, guest: 8000, host: 8000, auto_correct: true

    # Copy the default Vagrant ssh private key over
    local.vm.provision "file", source: "~/.vagrant.d/insecure_private_key", destination: "~/.ssh/insecure_private_key"
  end

  config.vm.define "server" do |server|
    # Private IP
    server.vm.network :private_network, ip: "192.168.72.3"
  end

end

Don't worry too much if you don't understand everything at first, I will explain a bit more in due time. Just know that this config will allow you to run two different machines: one will be your local one (conveniently named "local") and the other one (named "server") will be used to simulate a remote server.

For now, begin your journey with:

vagrant up local
vagrant ssh local

Unless stated otherwise, all the steps covered in this part and the next ones need to happen on the "local" machine.

Python, pip and virtualenv

Python

Pelican is written in Python and is installed via pip, the language's recommended tool to install packages (it is basically what npm is to JavaScript). Pelican works with Python 2.7.x, and chances are it is already available on your OS. To make sure of this, open a terminal and type:

python --version

If the command fails, please head to the installation guide and follow instructions for your platform.

Pelican should just work with Python 3.3+ as well, but as our intent is to use Fabric for deployment, we will stick to 2.7.x in this tutorial.

pip

If the version of Python you have is 2.7.9+, you are in luck because pip is already included. If not, install it this way:

wget https://bootstrap.pypa.io/get-pip.py -P /tmp/
sudo python /tmp/get-pip.py
rm /tmp/get-pip.py

The -P option allows to prefix the downloaded file with the destination folder ("/tmp/" in our case).

Let's take this opportunity of having pip handy to install Fabric straight away:

sudo pip install Fabric

We are going to use it soon enough.

We could now install Pelican right away using pip, but we are going to take an extra step before that.

virtualenv

If you are a developer, you may have come across situations where different projects need different versions of the same language to run, or different versions of other dependencies. Python is no exception to this, and it came up with a solution to address it: the use of Virtual Environments.

A Virtual Environment (VE) isolates a set of dependencies for a project. We are going to use virtualenv along with its buddy virtualenvwrapper to that purpose.

First, we need to install them using pip:

sudo pip install virtualenv
sudo pip install virtualenvwrapper

By default, virtualenv will create a folder named after the environment's directly inside the project's folder, and will do so for each project. virtualenvwrapper adds a set of functionalities on top of virtualenv to make its use easier, and placing all the VEs in the same folder is one of them (much cleaner IMHO and prevents us from having to add the folders in each project's .gitignore file).

Let's define where virtualenwrapper should gather all the folders:

echo 'export WORKON_HOME=$HOME/.virtualenvs' >> /home/vagrant/.bashrc
echo 'source /usr/local/bin/virtualenvwrapper.sh' >> /home/vagrant/.bashrc

Remember that I am using a Vagrant box here, hence "vagrant" as the username. Change this for the right value if necessary.

I place these commands at the end of my .bashrc file so that WORKON_HOME is correctly initialized any time I start a new shell.

Let's source our .bashrc file so the shell is updated with the new values:

source ~/.bashrc

It is now time to create our first VE. As we are setting up a blog, let's call it "blog":

mkvirtualenv blog

Your prompt should now look like this:

(blog)vagrant@vagrant-ubuntu-trusty-32:/vagrant$

Mind the "(blog)" bit at the beginning: it indicates that you are currently using the blog VE. mkvirtualenv not only creates it, but activates it as well.

This is how you leave it:

deactivate

Now let's check that the VE's folder was added to the right location:

ls $WORKON_HOME
ls ~/.virtualenvs

Both commands should give the same list, and the "blog" folder should be among them (only if you set ".virtualenvs" as the destination folder earlier, of course).

To activate your VE, use the following command:

workon blog

Here you are, ready to move on to the installation of Pelican itself.

Note that all the steps above is how you would prepare an environment for a Python project in general.

Just sayin' :)

In the next part, we will see how to install and configure Pelican in our shiny new environment.

Last updated by osteel on 2016-08-03 :: [ vagrant fabric tutorial python blog pelican ]