This article describes how to get a Pelican powered website up and running with minimal effort using a Vagrant virtual machine.

Pelican is a static html generator for creating blog style websites from simple text files in markdown, rst or creole syntax.

Vagrant is a tool for managing isolated development environments using VirtualBox virtual machines.

If all that means nothing to you, you might like to have a look at Pelican, Vagrant and VirtualBox first!

Installation

Pre-Requisites

There are four software tools which you will need on your machine for this project:

Setup

  • Clone the starter project repository to your machine:
 git clone --recursive https://github.com/meatballs/pelican-vagrant-starter.git
  • Start the virtual machine for the first time:
 cd <path to your repository>
 vagrant up

This will take some time. It has to download the operating system and all the tools to install on your new virtual machine.

  • Connect to your vm, exit and reload it:
    vagrant ssh
    <poke around to your heart's content>
    exit
    vagrant reload

Usage

  • Create your articles in the content folder. There are three samples there to start you off in markdown, rst and creole formats.
  • Modify the pelicanconf.py and publishconf.py to suit your situation. These are the standard Pelican config files and are described in the Pelican documentation.
  • Your virtual machine is running a web server which will detect changes to your content and show their effect immediately at http://localhost:8000. Pelican projects usually include a python script for this purpose, but it is not included in the starter project since the vm handles the task for you.
  • The starter project includes the voidy-bootstrap theme in the themes folder and configured in the pelicanconf.py file. You can download any other theme into the same folder and configure it for use.

Publishing

  • Configure your publishing setup using either the fabric or make tools as described in the Pelican documentation.
  • Login to your vm:
    vagrant ssh
  • Issue the the relevant publish command. e.g.
    make rsync_upload

Tips

  • You can issue a command directly to your vm without logging into a shell. e.g.
    vagrant ssh -c "cd /vagrant; make rsync_upload"
  • Your vm is configured to accept ssh agent forwarding so that your local ssh keys are available to it without needing to be copied. To use it you will have to configure your local machine to do so.

e.g. on a Mac, add the following to /.ssh/config:

    Host 127.0.0.1
        ForwardAgent yes
  • You can host your Pelican site with Github Pages. Instructions are in the Pelican tips and the ghp-import tool is already installed on your vm.


Comments

comments powered by Disqus