VoucherVault

Django web application to store and manage vouchers, coupons and gift cards digitally

💬 Description

VoucherVault is a Django web application that allows you to manage coupons, vouchers and gift cards digitally. It provides a web portal that is mobile friendly and easy to use.

Additionally, it supports expiry notifications via Apprise URLs that will frequently remind you to redeem your stuff. You can also track fractional transactions, which help to understand historical redemptions and reflect the remaining monetary value of an item accurately.

Finally, redeem codes are nicely printed as QR code or EAN13 barcode.

🐳 Usage

docker compose -f docker/docker-compose.yml up

Once the container is up and running, you can access the web portal at http://127.0.0.1:8000.

The default username is admin. The default password is auto-generated.

You can obtain the auto-generated password via the Docker container logs:

docker compose -f docker/docker-compose.yml logs -f

Warning

The container runs as low-privileged www-data user. So you have to adjust the permissions for the persistent database bind mount volume. A command like sudo chown -R www-data:www-data <path-to-volume-data-dir> should work. Afterwards, please restart the container.

🌍 Environment Variables

The docker container takes various environment variables:

Variable	Description	Default	Optional/Mandatory
DOMAIN	Your Fully Qualified Domain Name (FQDN) or IP address. Used to define ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS for the Django framework.	localhost	Mandatory
SECURE_COOKIES	Set to True if you use a reverse proxy with TLS. Enables the secure cookie flag and HSTS HTTP response header, which will only work for SSL/TLS encrypted communication channels (HTTPS).	False	Optional
EXPIRY_THRESHOLD_DAYS	Defines the days prior item expiry when an Apprise expiry notification should be sent out.	30	Optional
SECRET_KEY	Defines a fixed secret key for the Django framework. If missing, a secure secret is auto-generated on the server-side each time the container starts.	<auto-generated>	Optional
PORT	Defines a custom port. Used to set CSRF_TRUSTED_ORIGINS in conjunction with the DOMAIN environment variable for the Django framework. Only necessary, if VoucherVault is operated on a different port than 8000, 80 or 443.	8000	Optional
REDIS_HOST	Defines the Redis instance to use for Django-Celery-Beat task processing.	redis	Optional

🔔 Notifications

Notifications are handled by Apprise.

You can define custom Apprise URLs in the user profile settings. The input form takes a single or a comma-separated list of multiple Apprise URLs.

The interval, how often items are checked against a potential expiry, is pre-defined (every Monday at 9AM) in the Django admin area. Here, we are utilizing Django-Celery-Beat + a Redis instance for periodic task execution. If you want to adjust the crontab interval, please head over to the admin area at Periodic Tasks > Periodic Expiry Check > Crontab Schedule > Edit and adjust to your liking.

An item will trigger an expiry notification if the expiry date is within the number of days defined by the environment variable EXPIRY_THRESHOLD_DAYS. By default, this threshold is set to 30 days.

🔐 Multi-User Setup

VoucherVault is initialized with a default superuser account named admin and a secure auto-generated password.

This administrative account has full privileges to the Django admin panel, located at /admin. Therefore, all database model entries can be read and modified by this user. Additionally, new user accounts and groups can be freely created too.

For simplicity, VoucherVault makes use of the default Django authentication scheme for Superusers and Staff Users.

Caution

If you create new users on VoucherVault, you must at least assign the Staff status privilege. This indicates and ensures that the new user account can use the VoucherVault login area at /admin, although not being a superuser with high privileges.

📷 Screenshots

Tip

Support for light and dark theme available!

💾 Backups

All application data is stored within an SQLite3 database. The database is persistently stored within a Docker bind mount volume, which is defined in the docker-compose.yml file. The default location is defined as ./volume-data/database/db.sqlite3.

Therefore, by backing up this bind mount volume, all your application data is saved.

Warning

Read the official SQLite3 documentation regarding backups.

Manual Django Backups

You can alternatively dump the SQLite database content manually using Django's manage.py. This may help if something bricks and you have to re-import your application data into a freshly spawned VoucherVault container.

Proceed as follows:

Export data | Create Backup

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

# export sqlite3 database tables into outfile
python manage.py dumpdata auth.group > database/backup_db_table_groups.json
python manage.py dumpdata auth.user > database/backup_db_table_users.json
python manage.py dumpdata myapp.item > database/backup_db_table_items.json
python manage.py dumpdata myapp.transaction > database/backup_db_table_transactions.json

Import data | Recover Backup:

# import old backup outfiles into sqlite3
python manage.py loaddata database/backup_db_table_groups.json
python manage.py loaddata database/backup_db_table_users.json
python manage.py loaddata database/backup_db_table_items.json
python manage.py loaddata database/backup_db_table_transactions.json