mirror of
https://github.com/etiennecollin/unifi-voucher-manager.git
synced 2025-10-23 00:02:10 +00:00
88bfa137e313c1313f3780ecf88f7ab9a4074250
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
- 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)
- Create the configuration files
# Download the compose file curl -o compose.yaml https://raw.githubusercontent.com/etiennecollin/unifi-voucher-manager/main/compose.yaml
- Configure your environment
- Set the required environment variables (see Environment Variables) in the
compose.yaml
file.
- Set the required environment variables (see Environment Variables) in the
- Start the application
docker compose up -d --force-recreate
- Access the interface
- Open your browser to
http://localhost:3000
.
- Open your browser to
Without Docker
-
Install the dependencies
rust >= 1.88.0
nodejs >= 24.3.0
npm >= 11.4.2
-
Clone the repository
git clone https://github.com/etiennecollin/unifi-voucher-manager
-
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 thedotenv
feature of the rust backend.
- In your shell, set the required environment variables (see Environment Variables)
or set them in a
-
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
-
Access the interface
- Open your browser to
http://localhost:3000
.
- Open your browser to
⚙️ 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 |
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
- Access your UniFi Controller
- Navigate to Settings -> Control Plane -> Integration
- Create a new API key by giving it a name and an expiration.
- 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 yourUNIFI_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
- Verify
- 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
- Run the container/backend with
⭐ If this project helped you, please consider giving it a star!
Languages
TypeScript
60.5%
Rust
24.3%
CSS
9.9%
Dockerfile
3.1%
Shell
2.1%