Deploying VoucherVault

Introduction

VoucherVault is a self-hosted application for managing your vouchers, gift cards, and loyalty cards in one centralized location. Never let a voucher expire unused or forget about a gift card balance again. VoucherVault helps you track expiration dates, remaining balances, and organize your vouchers by category.

Key highlights of VoucherVault:

Voucher Management: Store and organize all your vouchers in one place
Expiration Tracking: Get notifications before vouchers expire
Balance Tracking: Keep track of remaining balances on gift cards
Category Organization: Group vouchers by store, type, or custom categories
Barcode Support: Store and display barcodes for easy scanning
Image Uploads: Attach photos of physical vouchers
Multi-User: Support for multiple users with their own voucher collections
Mobile Friendly: Responsive design for access on any device
Self-Hosted: Your voucher data stays private on your own server

This guide walks through deploying VoucherVault on Klutch.sh using Docker, configuring the application, and managing your voucher collection.

Why Deploy VoucherVault on Klutch.sh

Deploying VoucherVault on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds VoucherVault without complex orchestration. Push to GitHub, and your voucher manager deploys automatically.

Persistent Storage: Attach persistent volumes for your database and voucher images. Your collection survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always Accessible: Access your vouchers 24/7 from any device when shopping.

Prerequisites

Before deploying VoucherVault on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for VoucherVault deployment.

Repository Structure

vouchervault-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM l4rm4nd/vouchervault:latest

# Set environment variables
ENV DJANGO_SECRET_KEY=${DJANGO_SECRET_KEY}
ENV DJANGO_DEBUG=${DJANGO_DEBUG:-False}
ENV DJANGO_ALLOWED_HOSTS=${DJANGO_ALLOWED_HOSTS:-*}
ENV DATABASE_URL=${DATABASE_URL:-sqlite:///data/db.sqlite3}
ENV TZ=${TZ:-UTC}

# Create data directories
RUN mkdir -p /data /data/media

# Expose the web interface port
EXPOSE 8000

# Volumes for persistent data
VOLUME ["/data"]

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8000/health/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`DJANGO_SECRET_KEY`	Yes	-	Django secret key for security
`DJANGO_DEBUG`	No	`False`	Enable debug mode (set to False in production)
`DJANGO_ALLOWED_HOSTS`	No	`*`	Allowed hostnames
`DATABASE_URL`	No	`sqlite:///data/db.sqlite3`	Database connection string
`TZ`	No	`UTC`	Timezone for expiration tracking

Deploying VoucherVault on Klutch.sh

Generate a Secret Key

Generate a secure Django secret key:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and configuration files.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “vouchervault” or “voucher-manager”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your VoucherVault Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8000

Set Environment Variables

Add the following environment variables:

Variable	Value
`DJANGO_SECRET_KEY`	Your generated secret key
`DJANGO_ALLOWED_HOSTS`	`your-app-name.klutch.sh`
`TZ`	Your timezone (e.g., `America/New_York`)

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
`/data`	5 GB	SQLite database and voucher images

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Access VoucherVault

Once deployment completes, access your VoucherVault instance at https://your-app-name.klutch.sh. Create an admin account on first access.

Managing Vouchers

Adding a Voucher

Click Add Voucher from the dashboard
Enter voucher details:
- Name/Description
- Store or brand
- Voucher code or number
- Initial balance (for gift cards)
- Expiration date
Optionally upload a barcode or image
Select or create a category
Save the voucher

Tracking Balances

For gift cards with remaining balances:

Open the voucher details
Click Update Balance
Enter the new balance after use
Save to track spending history

Expiration Alerts

Configure notifications for expiring vouchers:

Set your preferred notification timing
Enable email or browser notifications
Review upcoming expirations on the dashboard

Barcode Features

Adding Barcodes

When creating a voucher, click Add Barcode
Enter the barcode number manually, or
Upload an image of the barcode
Select the barcode format (Code128, QR, etc.)

Using Barcodes

At checkout:

Open VoucherVault on your phone
Find the voucher you want to use
Display the barcode for scanning
Update the balance after use

Multi-User Setup

Creating Users

Navigate to Settings > Users
Click Add User
Set username, email, and password
Assign permissions

Each user maintains their own voucher collection
Shared family vouchers can be visible to all users
Set voucher visibility per entry

Troubleshooting

Images Not Displaying

Verify the media volume is mounted correctly
Check file permissions on the data directory
Clear browser cache

Expiration Notifications Not Working

Verify timezone is set correctly
Check notification settings
Ensure background tasks are running

Reset password via email if configured
Check ALLOWED_HOSTS includes your domain
Verify SECRET_KEY hasn’t changed

Additional Resources

Conclusion

Deploying VoucherVault on Klutch.sh gives you a convenient, always-accessible voucher management system. The combination of VoucherVault’s tracking features and Klutch.sh’s deployment simplicity means you can stop losing value to expired vouchers and forgotten gift cards, accessing your collection from anywhere when you need it.