VoucherVault

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

⭐ Features

• Intuitive and mobile-friendly web portal
• Support for light and dark theme
• Support for vouchers, coupons, giftcards and loyalty cards
• Support for transaction histories (giftcards only)
• Support for file uploads per item (images and PDFs)
• Displaying redeem codes as QR code or EAN13 barcode
• Client-side camera scanning for 1D/2D (bar)codes during item creation
• Expiry notifications via Apprise
• Multi-user support via local auth
• Multi-user support via OIDC Single-Sign-On (SSO)
• Support for SQLite3 and PostgreSQL

🐳 Usage

READ THE WIKI

# create volume dir for persistence
mkdir -p ./volume-data/database

# adjust permissions
sudo chown -R www-data:www-data volume-data/*

# spawn the container stack
docker compose -f docker/docker-compose-sqlite.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-sqlite.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.

[!TIP] This repository follows the Conventional Commits standard. Therefore, you will find patch, minor and major release version tags on DockerHub. No one stops you from using the latest image tag but I recommend pinning a minor version series tag such as 1.5.x.

This is safer for automatic upgrades and you still get recent patches as well as bug fixes.

🌍 Environment Variables

The docker container takes various environment variables:

More details about the OIDC environment variables can be found here.

You can find detailed instructions on how to setup OIDC SSO in the wiki.

🔔 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.

Finally, Single-Sign-On (SSO) via OIDC is supported. Check out the environment variables above as well as the wiki.

📷 Screenshots

💾 Backups

All application data is stored within a Docker bind mount volume.

This volume is defined in the example Docker Compose files given. The default location is defined as ./volume-data/database.

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

[!WARNING] Read the official SQLite3 documentation or PostgreSQL documentation regarding backups.