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: 2 days 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 (6 months ago)
- Default Branch: main
- Last Pushed: 2024-12-06T18:44:35.000Z (24 days ago)
- Last Synced: 2024-12-21T18:08:47.712Z (9 days 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.9 MB
- Stars: 184
- Watchers: 5
- Forks: 3
- Open Issues: 0
-
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
- User-friendly, mobile-optimized web portal
- 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 EAN13 barcodes
- Client-side redeem code scanning (1D/2D) during item creation
- 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
## 📷 Screenshots
## 🐳 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.7.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 |
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). May read the [wiki](https://github.com/l4rm4nd/VoucherVault/wiki/03-%E2%80%90-Notifications).
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).
## 💾 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.
## 🤖 Repo Statistics
