Upgrading

Fietsboek does not currently have an automated updater, however it is quite simple to update Fietsboek manually.

Warning

Make sure to have backups of your user data ready in case the upgrade fails!

Note

It is advised to stop the Fietsboek server during the backup process.

Pulling the New Code

First, we need to pull the new code. This step depends on the source that you have installed Fietsboek from. In the case that you use git, this can be done in the following way:

git pull
git checkout v42.0  # Put in the version that you want to update to here

If you have downloaded an archive with the Fietsboek source, you need to download the archive with the new version and extract it somewhere.

Tip

If upgrading fails, try going in smaller steps, e.g. release by release. If you upgrade over a big version span, the chances are bigger that unintended interactions occur.

To do that, use git or pip to download specific versions of the code instead of going for the latest one.

Installing the Python Module

Use pip to install the new version of the Fietsboek package, as well as any new additional dependencies:

.venv/bin/pip install path/to/fietsboek/source

If you downloaded Fietsboek from PyPI, you may need to tell pip explicitely to upgrade. Otherwise it will simply say that the package is already installed:

.venv/bin/pip install --upgrade fietsboek

In general, this step is similar to the command that you used when installing Fietsboek initially.

Note that removed dependencies are not automatically removed. It might be worth to start with a clean virtual environment from time to time to clear out old cruft.

Upgrading the Database

Warning

It cannot be stressed enough that you should have backups of your data. This is your last chance.

Some updates might change the database schema. Those updates come with database migrations that can adapt an existing database to the new schema. In addition to database migrations, some updates also modify the on-disk data that Fietsboek stores.

Fietsboek comes with a handy tool that allows you to run the right database and file migrations: fietsupdate.

You can use the following command to upgrade to the latest installed version:

.venv/bin/fietsupdate update -c production.ini

Or you can view the status of your installation:

.venv/bin/fietsupdate status -c production.ini

Note

The fietsupdate tool is only there to run database migrations and other update tasks. It does not retrieve or install the correct code, please see the above sections to do that.

Restarting Fietsboek

You can now run Fietsboek again. This step depends on the method that you use to deploy Fietsboek.

Downgrading

In some cases, it might be required that you uninstall an update to Fietsboek, for example if it introduced a bug. Downgrading is possible and generally consists of two steps:

1. Restore the old data format (backwards migration)

2. Restore the old code

Warning

As with updates, make sure you have backups of your important data ready!

Restoring Data: Backups

The preferred way to use the old data is by restoring a backup, see Backup & Restore. This method ensures that your data is original and prevents the upgrade/downgrade process from inducing errors.

Restoring Data: Downgrading

If you do not have old backups of your data, you can use fietsupdate to convert your data from the new format to the old one. Please note that the upgrade process can not always be undone: If an update deletes data, even the downgrade cannot undo it. In such cases, the only way to restore the data is through a backup.

To use fietsupdate to downgrade your data, run the following command, replacing VERSION with the version you want to downgrade to:

.venv/bin/fietsupdate downgrade -c production.ini VERSION

Restoring Code

Now that the data has been restored to the old state, you need to restore the Fietsboek code to the old version. This works similarly to the update, with the difference that you should download and install the version of Fietsboek that you downgraded your data to.

If you use git, you can check out old versions of the code by using git checkout.

After obtaining the old code, don’t forget to install it into your virtual environment!