VoucherVault

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

⭐ Features

• User-friendly, mobile-optimized web portal with PWA support
• Manual offline mode with 48h caching supported
• Light and dark theme support
• Integration of vouchers, coupons, gift cards and loyalty cards
• Transaction history tracking (gift cards only)
• Item-specific file uploads (images and PDFs)
• Item sharing between users
• Display of redeem codes as QR codes or barcodes (many types supported)
• Client-side redeem code scanning (1D/2D) during item creation with automatic type detection using camera or file upload
• Expiry notifications via Apprise
• Multi-user support
• Multi-language support (English, German, French, Italian)
• Single Sign-On (SSO) via OIDC
• Database compatibility with SQLite3 and PostgreSQL
• REST API endpoint with stats for Home Assisstant (HA) and other dashboards
• Multi-currency support via free fixer.io API

📷 Screenshots

🐳 Usage

READ THE WIKI - UNRAID SUPPORTED

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

# adjust volume ownership to www-data
sudo chown -R 33:33 volume-data/*

# spawn the container stack
docker compose -f docker/docker-compose-sqlite.yml up -d

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 with UID/GID 33. So you have to adjust the permissions for the persistent database bind mount volume. A command like sudo chown -R 33:33 <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.28.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:

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

🔔 Notifications

Notifications are handled by Apprise. May read the wiki.

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 (daily at 9AM) in the Django admin area. Here, we are utilizing Django-Celery-Beat + a Redis instance for periodic task execution.

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. Additionally, a final reminder is sent out another time if the item expires within the next 7 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.

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

🤖 Repo Statistics