Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/l4rm4nd/VoucherVault
Django web application to store and manage vouchers, coupons, loyalty and gift cards digitally. Supports expiry notifications, transaction histories, file uploads and OIDC SSO.
https://github.com/l4rm4nd/VoucherVault
apprise asset-manager conventional-commits coupon coupon-management coupon-management-system coupons django5 expiration-control expiry-checker giftcard giftcards loyalty-cards loyaltycard oidc python3 selfhosting voucher vouchers vouchers-management
Last synced: 3 months ago
JSON representation
Django web application to store and manage vouchers, coupons, loyalty and gift cards digitally. Supports expiry notifications, transaction histories, file uploads and OIDC SSO.
- Host: GitHub
- URL: https://github.com/l4rm4nd/VoucherVault
- Owner: l4rm4nd
- License: gpl-3.0
- Created: 2024-07-07T18:16:23.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-08-07T22:54:32.000Z (3 months ago)
- Last Synced: 2024-08-08T18:13:56.879Z (3 months ago)
- Topics: apprise, asset-manager, conventional-commits, coupon, coupon-management, coupon-management-system, coupons, django5, expiration-control, expiry-checker, giftcard, giftcards, loyalty-cards, loyaltycard, oidc, python3, selfhosting, voucher, vouchers, vouchers-management
- Language: HTML
- Homepage: https://github.com/l4rm4nd/VoucherVault/wiki
- Size: 14.8 MB
- Stars: 120
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
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](https://github.com/l4rm4nd/VoucherVault/wiki/01-%E2%80%90-Installation)
````
# 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 ` 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:
| 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 |
| `TZ` | Defines the `TIME_ZONE` variable in Django's settings.py. | `Europe/Berlin` | 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. | `` | 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_URL` | Defines the Redis URL to use for Django-Celery-Beat task processing. | `redis://redis:6379/0` | Optional |
| `OIDC_ENABLED` | Set to `True` to enable OIDC authentication. | `False` | Optional |
| `OIDC_CREATE_USER` | Set to `True` to allow the creation of new users through OIDC. | `True` | Optional |
| `OIDC_RP_SIGN_ALGO` | The signing algorithm used by the OIDC provider (e.g., RS256, HS256). | `HS256` | Optional |
| `OIDC_OP_JWKS_ENDPOINT` | URL of the JWKS endpoint for the OIDC provider. Mandatory if `RS256` signing algo is used. | `None` | Optional |
| `OIDC_RP_CLIENT_ID` | Client ID for your OIDC RP. | `None` | Optional |
| `OIDC_RP_CLIENT_SECRET` | Client secret for your OIDC RP. | `None` | Optional |
| `OIDC_OP_AUTHORIZATION_ENDPOINT` | Authorization endpoint URL of the OIDC provider. | `None` | Optional |
| `OIDC_OP_TOKEN_ENDPOINT` | Token endpoint URL of the OIDC provider. | `None` | Optional |
| `OIDC_OP_USER_ENDPOINT` | User info endpoint URL of the OIDC provider. | `None` | Optional |
| `DB_ENGINE` | Database engine to use (e.g., `postgres` for PostgreSQL or `sqlite3` for SQLite3). | `sqlite3` | Optional |
| `POSTGRES_HOST` | Hostname for the PostgreSQL database. | `db` | Optional |
| `POSTGRES_PORT` | Port number for the PostgreSQL database. | `5432` | Optional |
| `POSTGRES_USER` | PostgreSQL database user. | `vouchervault` | Optional |
| `POSTGRES_PASSWORD` | PostgreSQL database password. | `vouchervault` | Optional |
| `POSTGRES_DB` | PostgreSQL database name. | `vouchervault` | Optional |
More details about the OIDC environment variables can be found [here](https://mozilla-django-oidc.readthedocs.io/en/stable/settings.html).
You can find detailed instructions on how to setup OIDC SSO in the [wiki](https://github.com/l4rm4nd/VoucherVault/wiki/02-%E2%80%90-Authentication#oidc-authentication).
## 🔔 Notifications
Notifications are handled by [Apprise](https://github.com/caronc/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](https://github.com/l4rm4nd/VoucherVault/wiki/02-%E2%80%90-Authentication#oidc-authentication).
## 📷 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](https://sqlite.org/backup.html) or [PostgreSQL documentation](https://www.postgresql.org/docs/current/backup.html) regarding backups.