01 ‐ Installation
VocherVault builds and releases multi-arch Docker images automatically via a GitHub CI on DockerHub.
Therefore, you can use the pre-build images without building locally yourself.
VoucherVault follows the Conventional Commits specification.
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.6.x. This is safer for automatic upgrades and you still get recent patches as well as bug fixes.
In short:
- Small code changes, bug fixes and refactorings will be released by bumping the patch version (e.g. from 1.4.1 to 1.4.2)
- New features will be released by bumping the minor version (e.g. from 1.4.1 to 1.5.0)
- Breaking changes will be released by bumping the major version (e.g. from 1.4.1 to 2.0.0)
Multiple example Docker Compose files are provided in the repo's docker directory.
For an easy installation and most users, it is recommended to use docker-compose-sqlite.yml.
If you want to use a PostgreSQL database engine or implement OIDC SSO, check out the other examples given.
To spawn VoucherVault, follow these steps:
# create volume dir for persisted container data
mkdir -p ./volume-data/database
# adjust permissions
sudo chown -R www-data:www-data volume-data/*
# spawn the container stack
docker compose -f 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.
Warning
If you access VoucherVault from a different URL than localhost or 127.0.0.1, you must set your FQDN via the env variable DOMAIN.
Otherwise, you will observe CSRF and/or ALLOWED_HOSTS errors (e.g. bad request (400)).
Tip
Instead of defining sensitive secrets as environment variables directly within the docker-compose.yml file, you can make use of a separate env.example file. You can find an example file provided in the docker directory of this repository. This way, you do not disclose secrets in the YAML file itself.
More information here.
The default username is called admin.
The default password is auto-generated. You can obtain the password via container logs:
docker compose -f docker-compose-sqlite.yml logs -f
The VoucherVault 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. | <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_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_RP_IDP_SIGN_KEY |
The signing key used by the OIDC provider. If RS256 signing algo is used, either this or OIDC_OP_JWKS_ENDPOINT must be defined. |
None |
Optional |
OIDC_OP_JWKS_ENDPOINT |
URL of the JWKS endpoint for the OIDC provider. If RS256 signing algo is used, either this or OIDC_RP_IDP_SIGN_KEY must be defined. |
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 |
VoucherVault makes use of Docker bind mount volumes.
The Docker Compose files provided declare a single volume mapping. The container's database folder is mapped to the Docker host server.
This is necessary to persist data over container restarts.
The default location where the container's database data is mounted on your Docker host server is:
./volume-data/database
Within this directory on your server, you will find:
- The
db.sqlite3file ifsqlite3is used as database engine (default) - The
psqldirectory, which holds your PostgreSQL database data ifpostgresis used as database engine - The
uploadsdirectory, which holds a subdirectory per user with user-specific file uploads (PDFs and images)
The container runs as low-privileged www-data user.
Therefore, you have to ensure proper permissions for the persistent database bind mount volume.
Otherwise, you will get the following errors:
sqlite3.OperationalError: unable to open database filedjango.db.utils.OperationalError: unable to open database file
The following command may fix permission issues:
sudo chown -R www-data:www-data ./volume-data/*The container exposes an unencrypted HTTP web service on TCP/8000. You can freely proxy to it. No specific setup required. Though, subdomain routing is recommended over path-related routing.
If a reverse proxy is used, you must set:
-
DOMAINto your FQDN -
SECURE_COOKIESoptionally toTrueto get HSTS header enabled as well as theSecurecookie flag
Please check out the supported environment variables above for more information.
For Unraid users there exists an official community app published by LRVT.
The template XML can be found here.
Choose the community app provided by LRVT and click Install.
Then:
- Ensure the latest VoucherVault tag is defined at
Repository(e.g.1.5.x). - Fill out your UNRAID IP or subdomain in the
DOMAINenvironment variable.
Afterwards, click APPLY to spawn the Docker container. This will pull the Docker image and start the container.
The container will fail to start due to permission issues. That is normal on Unraid OS.
To fix these permission issues, you have to adjust the share permissions and make the www-data user with UID/GID 33 an owner.
Log into Unraid, spawn a terminal shell as root via the UI and execute this command:
chown -R 33:33 /mnt/user/appdata/vouchervault
Then restart the VoucherVault docker container via the UI.
Afterwards, VoucherVault will be available on http://<UNRAID-IP>:8000.
The default admin password is auto-generated.
Just inspect the container logs and you will find them.
For expiry notifications to work, you must also spawn a Redis container.
There exists an official community app for Redis:
The redis container must be named redis-vouchervault.
Warning
If you do not name the redis container redis-vouchervault, you must adjust the environment variable REDIS_URL in VoucherVault.
Afterwards, just click APPLY to spawn the Redis container.
Now, Redis and VoucherVault will interact with each other and periodic expiry notifications will work.
