UniFi Voucher Manager

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
• 🐛 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
• View All Vouchers - Browse and search existing vouchers by name
• Search Vouchers - Search vouchers by name
• Bulk Operations - Select and delete multiple vouchers
• Auto-cleanup - Remove expired vouchers with a single click
• QR Code - Easily connect guests to your network

🎨 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
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

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