unifi-voucher-manager/README.md

UniFi Voucher Manager

UVM is a modern, touch-friendly web application for managing WiFi vouchers on UniFi controllers. Perfect for businesses, cafes, hotels, and home networks that need to provide guest WiFi access.

• ✨ Features
  • 🎫 Voucher Management & WiFi QR Code
  • 🎨 Modern Interface
  • 🔧 Technical Features
• 🚀 Quick Start
  • Using Docker Compose (Recommended)
  • Without Docker
• ⚙️ Configuration
  • Environment Variables
  • Getting UniFi API Credentials
  • Rolling Vouchers and Kiosk Page
    • How Rolling Vouchers Work
    • Kiosk Display
• 🐛 Troubleshooting
  • Common Issues
  • Getting Help

✨ Features

🎫 Voucher Management & WiFi QR Code

• Quick Create - Generate guest vouchers with preset durations (1 hour to 1 week)
• Custom Create - Full control over voucher parameters:
  • Custom name
  • Duration (minutes to days)
  • Guest count limits
  • Data usage limits
  • Upload/download speed limits
• Browse Vouchers - Browse and search existing vouchers by name
• Bulk Operations - Select and delete multiple vouchers at once
• Print Vouchers - Print vouchers in either list or grid format; thermal printers friendly
• Auto-cleanup - Remove expired vouchers with a single click
• QR Code - Easily connect guests to your network
• Rolling Vouchers - Automatically generate a voucher for the next guest when the current one gets used
• Kiosk Page - A nice page to display your QR code and current rolling voucher

🎨 Modern Interface

• Touch-Friendly – Optimized for tablet, mobile, and desktop
• Dark/Light Mode – Follows system preference, with manual override
• Responsive Design - Works seamlessly across all screen sizes
• Smooth Animations – Semantic transitions for polished UX
• Real-time Notifications - Instant feedback for all operations

🔧 Technical Features

• Docker Ready - Easy deployment with Docker Compose and included healthcheck
• UniFi Integration - Direct API connection to UniFi controllers
• Secure Architecture - Next.js (TypeScript + Tailwind CSS) frontend with an Axum-based Rust backend that handles all UniFi Controller communication, keeping credentials isolated from the user-facing UI

🚀 Quick Start

Using Docker Compose (Recommended)

1. Create the configuration files

   # Download the compose file
   curl -o compose.yaml https://raw.githubusercontent.com/etiennecollin/unifi-voucher-manager/main/compose.yaml
   

2. Configure your environment
   • Set the required environment variables (see Environment Variables) in the compose.yaml file.
3. Start the application

   docker compose up -d --force-recreate
   

4. Access the interface
   • Open your browser to http://localhost:3000.

Without Docker

1. Install the dependencies

   • rust >= 1.88.0
   • nodejs >= 24.3.0
   • npm >= 11.4.2

2. Clone the repository

   git clone https://github.com/etiennecollin/unifi-voucher-manager
   

3. Configure your environment

   • In your shell, set the required environment variables (see Environment Variables) or set them in a .env file at the root of the repository and use the dotenv feature of the rust backend.

4. Start the frontend and backend

   # Backend (without using a .env file)
   cd backend && cargo run --release
   
   # Backend (using a .env file)
   cd backend && cargo run --release --features dotenv
   
   # Frontend (development)
   cd frontend && npm install && npm run dev
   
   # Frontend (release)
   cd frontend && npm ci && npm run build && npm run start
   

5. Access the interface

   • Open your browser to http://localhost:3000.

⚙️ Configuration

Environment Variables

Make sure to configure the required variables. The optional variables generally have default values that you should not have to change.

To configure the WiFi QR code, you are required to configure the WIFI_SSID and WIFI_PASSWORD variables.

Variable	Required?	Description	Example	Type
UNIFI_CONTROLLER_URL	Required	URL to your UniFi controller with protocol (http:// or https://).	https://unifi.example.com or https://192.168.8.1:443	string
UNIFI_API_KEY	Required	API Key for your UniFi controller.	abc123...	string
UNIFI_HAS_VALID_CERT	Optional	Whether your UniFi controller uses a valid SSL certificate. This should normally be set to true, especially if you access the controller through a reverse proxy or another setup that provides trusted certificates (e.g., Let's Encrypt). If you connect directly to the controller’s IP address (which usually serves a self-signed certificate), you may need to set this to false.	true (default)	bool
UNIFI_SITE_ID	Optional	Site ID of your UniFi controller. Using the value default, the backend will try to fetch the ID of the default site.	default (default)	string
GUEST_SUBNETWORK	Optional	Restrict guest subnetwork access to UVM while still permitting access to the /welcome page, which users are redirected to from the UniFi captive portal. For more details, see Rolling Vouchers and Kiosk Page.	10.0.5.0/24	IPv4 CIDR
FRONTEND_BIND_HOST	Optional	Address on which the frontend server binds.	0.0.0.0 (default)	IPv4
FRONTEND_BIND_PORT	Optional	Port on which the frontend server binds.	3000 (default)	u16
FRONTEND_TO_BACKEND_URL	Optional	URL where the frontend will make its API requests to the backend.	http://127.0.0.1 (default)	URL
BACKEND_BIND_HOST	Optional	Address on which the server binds.	127.0.0.1 (default)	IPv4
BACKEND_BIND_PORT	Optional	Port on which the backend server binds.	8080 (default)	u16
BACKEND_LOG_LEVEL	Optional	Log level of the Rust backend.	info(default)	trace|debug|info|warn|error
TIMEZONE	Optional	Timezone identifier used to format dates and time.	UTC (default)	timezone identifier
ROLLING_VOUCHER_DURATION_MINUTES	Optional	Number of minutes each rolling voucher will be valid for once activated.	480 (default)	minutes
WIFI_SSID	Optional	WiFi SSID used for the QR code. (required for QR code to be generated)	My WiFi SSID	string
WIFI_PASSWORD	Optional	WiFi password used for the QR code. If the WiFi network does not have a password, set to an empty string "". (required for QR code to be generated)	My WiFi Password	string
WIFI_TYPE	Optional	WiFi security type used. Defaults to WPA if a password is provided and nopass otherwise.	WPA	WPA|WEP|nopass
WIFI_HIDDEN	Optional	Whether the WiFi SSID is hidden or broadcasted.	false (default)	bool

Getting UniFi API Credentials

1. Access your UniFi Controller
2. Navigate to Settings -> Control Plane -> Integration
3. Create a new API key by giving it a name and an expiration.
4. Find your Site ID in the controller URL or on unifi.ui.com

Rolling Vouchers and Kiosk Page

Rolling vouchers provide a seamless way to automatically generate guest network access codes. When one voucher is used, a new one is automatically created for the next guest.

Important

UniFi Controller Setup Required

For rolling vouchers to work properly, you must configure your UniFi Hotspot:

1. Go to your UniFi Controller -> Insights -> Hotspot
2. Set the Success Landing Page to: https://your-uvm-domain.com/welcome, the /welcome page of UVM
3. To restrict UVM access to the guest subnetwork while still allowing access to /welcome set the GUEST_SUBNETWORK environment variable

Without this configuration, vouchers will not automatically roll when guests connect.

How Rolling Vouchers Work

1. Initial Setup: Rolling vouchers are generated automatically when needed
2. Guest Connection: When a guest connects to your network, they're redirected to the /welcome page
3. Automatic Rolling: The welcome page triggers the creation of a new voucher for the next guest
   • Rolling vouchers are created with special naming conventions to distinguish them from manually created vouchers, making them easy to identify in your voucher management interface
4. IP-Based Uniqueness: Each IP address can only generate one voucher per session (prevents abuse from page reloads)
5. Daily Maintenance: To prevent clutter, expired rolling vouchers are automatically deleted at midnight (based on your configured TIMEZONE in Environment Variables)

Kiosk Display

The kiosk page (/kiosk) provides a guest-friendly interface displaying:

• QR Code: For easy network connection (if configured in Environment Variables)
• Current Voucher: The active rolling voucher code
• Real-time Updates: Automatically refreshes when vouchers change

🐛 Troubleshooting

Common Issues

• Vouchers not appearing or connection issue to UniFi controller
  • Verify UNIFI_CONTROLLER_URL is correct and accessible
  • Verify UNIFI_SITE_ID matches your controller's site
  • Verify UNIFI_HAS_VALID_CERT is correct (depending on whether your UNIFI_CONTROLLER_URL has a valid SSL certificate or not)
  • Check if the UniFi controller is running and reachable (DNS issues?)
  • Ensure API key is valid
  • Ensure the site has the hotspot/guest portal enabled
• Application won't start
  • Check all environment variables are set
  • Verify Docker container has network access to UniFi controller
  • Check logs: docker logs unifi-voucher-manager
• The WiFi QR code button is disabled
  • Check the Environment Variables section and make sure you configured the variables required for the WiFi QR code
  • Check the browser console for variable configuration errors (generally by hitting F12 and going to the 'console' tab)

Getting Help

• Check the Issues page
• Create a new issue with detailed information about your problem
• Include relevant logs and environment details (redact sensitive information)
  • Run the container/backend with BACKEND_LOG_LEVEL="debug"
  • Include Docker logs: docker logs unifi-voucher-manager
  • Include browser logs: generally by hitting F12 and going to the 'console' tab of your browser

---

⭐ If this project helped you, please consider giving it a star!