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
  • Kiosk Display
  • 🎨 Modern Interface
  • 🔧 Technical Features
• 🚀 Quick Start
  • Using Docker Compose (Recommended)
  • Without Docker
• ⚙️ Configuration
  • Getting UniFi API Credentials
  • Rolling Vouchers and Kiosk Page
    • How Rolling Vouchers Work
  • Environment Variables
• 🐛 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 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 the rolling voucher changes

🎨 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

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

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

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

Caution

To restrict UVM access to the guest subnetwork users while still allowing access to /welcome page, set the GUEST_SUBNETWORK environment variable. This makes sure guests do not have access to other UVM pages, such as the voucher management interface (the root / page).

Without this configuration, guests will be able to access the voucher management interface of UVM. This means they will be able to both create and delete vouchers by themselves.

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)

Environment Variables

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

Tip

• To configure the WiFi QR code, you are required to configure the WIFI_SSID and WIFI_PASSWORD variables.
• For proper timezone, make sure to set the TIMEZONE variable.

Important

Make sure to expand this section and read what the environment variables are doing. Some variables are required, they are placed at the top of the list.

• UNIFI_CONTROLLER_URL: string (Required)
  • Description: URL to your UniFi controller with protocol (http:// or https://).
  • Example: https://unifi.example.com or https://192.168.8.1:443
• UNIFI_API_KEY: string (Required)
  • Description: API Key for your UniFi controller.
  • Example: abc123...

Warning

Improperly setting the UNIFI_HAS_VALID_CERT variable will prevent UVM from communicating with the UniFi controller.

• UNIFI_HAS_VALID_CERT: bool (Optional)
  • Description: 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.
  • Example: true (default)
• UNIFI_SITE_ID: string (Optional)
  • Description: Site ID of your UniFi controller. Using the value default, the backend will try to fetch the ID of the default site.
  • Example: default (default)

Caution

To restrict UVM access to the guest subnetwork users while still allowing access to /welcome page, set the GUEST_SUBNETWORK variable. This makes sure guests do not have access to other UVM pages, such as the voucher management interface (the root / page).

Without this configuration, guests will be able to access the voucher management interface of UVM. This means they will be able to both create and delete vouchers by themselves.

• GUEST_SUBNETWORK: IPv4 CIDR (Optional)
  • Description: 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.
  • Example: 10.0.5.0/24
• FRONTEND_BIND_HOST: IPv4 (Optional)
  • Description: Address on which the frontend server binds.
  • Example: 0.0.0.0 (default)
• FRONTEND_BIND_PORT: u16 (Optional)
  • Description: Port on which the frontend server binds.
  • Example: 3000 (default)
• FRONTEND_TO_BACKEND_URL: URL (Optional)
  • Description: URL where the frontend will make its API requests to the backend.
  • Example: http://127.0.0.1 (default)
• BACKEND_BIND_HOST: IPv4 (Optional)
  • Description: Address on which the server binds.
  • Example: 127.0.0.1 (default)
• BACKEND_BIND_PORT: u16 (Optional)
  • Description: Port on which the backend server binds.
  • Example: 8080 (default)
• BACKEND_LOG_LEVEL: trace|debug|info|warn|error (Optional)
  • Description: Log level of the Rust backend.
  • Example: info(default)
• TIMEZONE: timezone identifier (Optional)
  • Description: Timezone identifier used to format dates and time.
  • Example: UTC (default)
• ROLLING_VOUCHER_DURATION_MINUTES: minutes (Optional)
  • Description: Number of minutes a rolling voucher will be valid for once activated.
  • Example: 480 (default)
• WIFI_SSID: string (Optional)
  • Description: WiFi SSID used for the QR code. (required for QR code to be generated)
  • Example: My WiFi SSID
• WIFI_PASSWORD: string (Optional)
  • Description: 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)
  • Example: My WiFi Password
• WIFI_TYPE: WPA|WEP|nopass (Optional)
  • Description: WiFi security type used. Defaults to WPA if a password is provided and nopass otherwise.
  • Example: WPA
• WIFI_HIDDEN: bool (Optional)
  • Description: Whether the WiFi SSID is hidden or broadcasted.
  • Example: false (default)

🐛 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!