Install and deploy a Pelican blog using Fabric - Part 1: local environmentLast updated: 2016/08/03 :: [ changelog ]
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.
- Part 1: local environment
- Part 2: installation and configuration
- Part 3: Fabric
- Part 4: workflow, extras and conclusion
The Vagrant way
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
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.
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
-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.
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.
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.
source our .bashrc file so the shell is updated with the new values:
It is now time to create our first VE. As we are setting up a blog, let's call it "blog":
Your prompt should now look like this:
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:
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:
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.