Pelican comes out with new versions fairly regularly, which I like to keep up with. Pelican supports in place upgrades, but I prefer to get the new version fully working with my set-up before I nuke the one I'm using to write content. So my process is to do a new install and then add my content.
If you'd like to short-cut all the hassle then Pelican supports an upgrade command. According to the documentation you can do:
(PelicanVirt)$ pip install --upgrade pelican
But, that's a bit too aggressive for me so I do the following steps.
1. Make sure the production set-up is repeatable
The first step is to make sure that the current virtualenv and set-up are easy to install and set-up. If there's a problem with the upgrade process we want to be able to get back to this set-up. There are two steps - ensuring that all the Python dependancies are recorded, and tagging the production site code in revision control system.
To make sure that the Python dependancies are recorded we use pip, or pip-tools. Since we're check-pointing this state it's worth taking the time to update all dependancies and test that everything works first:
# Do any updating and test everything works (PelicanCurr)$ pip freeze > requirements.txt
Note: For illustration in this post my production virtualenv environment is called PelicanCurr and the new upgraded environment will be called Pelican3.4
I'm using Pip-tools as I also have some development requirements which I keep in dev-requirements.txt:
# Do any updating (PelicanCurr)$ pip-review --interactive # Test everything and then when ready: (PelicanCurr)$ pip-dump --verbose # It writes to requirements.txt and dev-requirements.txt
Now that everything is up to date we tag it in version control. I'm using Bazaar, so this means doing:
# Update to the latest code and then checkin everything (PelicanCurr)$ bzr update (PelicanCurr)$ bzr checkin # Tag the current code with the version number of pelican or any other tag (PelicanCurr)$ bzr tag pelican-3.3
2. Read the release notes
Read through the release notes and see if there's anything interesting or something that breaks backwards compatibility. You can also read through the issue list for more detail.
3. Create a virtualenv environment for the upgrade:
# Return to the normal command line (PelicanCurr)$ deactivate $ mkproject --no-site-packages Pelican3.4 (Pelican3.4)$
For me virtualenv complains that --no-site-packages is the default. This creates a new environment and sets me into ~/workspace/Pelican3.4:.
4. Install the new Pelican version:
(Pelican3.4) $ pip install pelican # It does a lot of things!
This uses Pip to install Pelican along with any dependencies that it requires. There are quite a few and you can list what's in the system with lssitepackages to get an idea.
5. Check the installed packages against the previous install:
According to the output from the install command it did the following:
Successfully installed pelican feedgenerator jinja2 pygments docutils pytz blinker unidecode six python-dateutil markupsafe
We can compare this against the old system:
(Pelican3.4)$ pip install yolk (Pelican3.4)$ yolk --list
Then in your old virtualenv, and in the new one run yolk --list and compare the output. Any that you know you'll need you can install. In my case this turned up a list along these lines:
Jinja2 MarkupSafe #Pillow - not in the new environment and not needed as I'm not using the plugin Pygments Python Unidecode argparse #beautifulsoup4 - needed for tipue_search so installed later blinker distribute docutils feedgenerator pelican pip python-dateutil pytz #selenium? - not needed yet, used for testing six #smartypants - not needed yet #splinter - not needed yet, used with selenium for testing #typogrify - not needed yet wsgiref yolk
Note: not obeying my own rules meant I didn't have my requirements.txt up to date, so I missed that I needed markdown
6. Check out the site from revision control
We're ready to get the content so that we can test the new set-up:
(Pelican3.4)$ bzr checkout sftp://user@mysite.com/path/to/repository/ # downloads all your content
7. Deal with static files that may have changed:
In the top-level of the Pelican directory there is a Makefile, the development server script and a fabric file (fabfile.py). It's worth updating to the new Makefile and development server script so that everything stays in sync with the release. First we check that we're happy with them (using Meld) and then we copy them across:
$ cd ~/.virtualenvs/Pelican3.4/lib/python2.7/site-packages/pelican/tools/templates/ $ meld develop_server.sh ~/Pelican3.4/develop_server.sh $ cp develop_server.sh ~/Pelican3.4/develop_server.sh
10. Start testing
We have the new version of Pelican (3.4), with the sites current working configuration and existing content ready for testing:
(Pelican3.4)$ make devserver **KABOOM!**
Hmm, nothing worked for me and it couldn't generate any content or start the server. Rather than having the devserver constantly running I stopped it and then generated the content manually looking for error messages:
$ make stopserver $ pelican content --debug -s pelicanconf.py 2>&1 | grep -E "ERROR|DEBUG"
Note: It's sometimes hard to get the devserver to stop so ''netstat -tcp -udp --listening --program'' can be useful.
11. Solve any problems
WARNING: PLUGIN_PATH setting has been replaced by PLUGIN_PATHS, moving it to the new setting name.
WARNING: Defining PLUGIN_PATHS setting as string has been deprecated (should be a list)``
<h1> {{ article.date.strftime('%e %b %Y', safe=False) }} </h1>
(Pelican3.4)$ pip install beautifulsoup4
(Pelican3.4)$ pip install markdown
12. Update the requirements.txt
The last thing to do is to update requirements.txt and dev-requirements.txt with the new versions of everything. If there are old dependencies that are no-longer needed these will be removed, so it's worth remembering why they are there and commenting requirements.txt accordingly:
(Pelican3.4)$ pip-dump --verbose
Now, if you have any other environments where you want to set-up your Pelican3.4 environment you can easily do pip install -r requirements.txt
That completes all the steps for the upgrade. You're now ready to write content and publish it again. I don't think this is the fastest way of upgrading Pelican, but so far it's the safest way I've found!