Upgrading to a newer VoucherVault release version is typically straight-forward.

How to Upgrade

1. Backup your Docker bind mount volume according to this wiki entry
2. Stop the VoucherVault stack via docker compose down
3. Edit the docker-compose.yml and pin the newly released version tag
4. Spawn the VoucherVault stack via docker compose up -d

Once spawned, an automatic database migration takes place. This will adjust the database model if necessary and ensures that the new VoucherVault instance works with your old data. The logs will look like the following:

vouchervault        | [~] Identified database file db.slite3. Skipping DB init.
vouchervault        | [~] Migrating changes to the database
vouchervault        | No changes detected
vouchervault        | No changes detected in app 'myapp'
vouchervault        | Operations to perform:
vouchervault        |   Apply all migrations: admin, auth, contenttypes, django_celery_beat, myapp, sessions
vouchervault        | Running migrations:
vouchervault        |   Applying myapp.0002_item_file... OK
vouchervault        |   Applying myapp.0003_remove_item_file_item_file_content_type_and_more... OK
vouchervault        |   Applying myapp.0004_remove_item_file_content_type_remove_item_file_data_and_more... OK
vouchervault        |   Applying myapp.0005_remove_item_file_item_file_path... OK
vouchervault        |   Applying myapp.0006_remove_item_file_path_item_file... OK
vouchervault        |   Applying myapp.0007_alter_item_file... OK
vouchervault        |   Applying myapp.0008_item_value_type... OK
vouchervault        | Operations to perform:
vouchervault        |   Apply all migrations: myapp
vouchervault        | Running migrations:
vouchervault        |   No migrations to apply.
vouchervault        | [~] Starting Celery worker and beat
vouchervault        | [i] Changing DB ownership to www-data
vouchervault        | [i] Spawning the application server

Then, you can log into your VoucherVault instance and enjoy the new features and bug fixes.

Troubleshooting

In rare circumstances, it may be possible that a new VoucherVault version and upgrade does not work for you.

If so, you have to troubleshoot and provide your logs via GitHub issues.

Manual Database Migration

Sometimes, automatic database migrations in Django do not work.

Especially, if a new VoucherVault version introduces new database model fields or adjusted older ones. In this case, your old database scheme must be upgraded.

You can issue a manual database migration like so:

# exec into the vouchervault container
docker exec -it vouchervault bash

# collect migrations
python manage.py makemigrations
python manage.py makemigrations myapp

# make migrations
python manage.py migrate
python manage.py migrate myapp

[!WARNING] During manual migrations you may be asked to provide a default value. This occurs, if there is a new database model, which requires a mandatory field. Your old database items do not have this database field yet. Therefore, you must provide a default value.

Container Error Logging

You may find helpful error messages in the container logs:

docker compose logs -f

Enabling Django Debug Mode

You can use the environment variable DEBUG and set it to True.

This way, if the Django web application is browsable, you will receive helpful debug messages in the browser in case something goes wrong.