paulmataruso/unifi-voucher-manager
1
0
Fork 0
mirror of https://github.com/etiennecollin/unifi-voucher-manager.git synced 2025-10-23 00:02:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improved template compose file and environment variables documentation

Browse Source
This commit is contained in:
etiennecollin
2025-08-16 23:00:45 -04:00
parent 4bc0c8b467
commit fdeb429c5a
2 changed files with 34 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@@ -115,23 +115,23 @@ Make sure to configure the required variables. The optional variables generally
To configure the WiFi QR code, you are required to configure the `WIFI_SSID` and `WIFI_PASSWORD` variables.
| Variable | Type | 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 has a valid, non-self signed certificate. **If you directly use the controller IP address in the URL, this should probably be set 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) used to format dates and time. | `UTC` (default) | [`timezone`](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) |
| `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 (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` |
| 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) used to format dates and time. | `UTC` (default) | [`timezone identifier`](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) |
| `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
@@ -147,13 +147,14 @@ To configure the WiFi QR code, you are required to configure the `WIFI_SSID` and
- **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
- Check if UniFi controller is running and reachable
- 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 hotspot/guest portal enabled
- 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 compose logs unifi-voucher-manager`
- Check logs: `docker logs unifi-voucher-manager`
- **The WiFi QR code button is seems disabled**
- Check the [Environment Variables](#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).
@@ -163,6 +164,9 @@ To configure the WiFi QR code, you are required to configure the `WIFI_SSID` and
- Check the [Issues](https://github.com/etiennecollin/unifi-voucher-manager/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
---

17
compose.yaml
View File

@@ -1,22 +1,25 @@
---
services:
unifi-voucher-manager:
image: "etiennecollin/unifi-voucher-manager:latest"
image: "docker.io/etiennecollin/unifi-voucher-manager:latest"
# Or use the github registry
# image: "ghcr.io/etiennecollin/unifi-voucher-manager:latest"
# To build the image yourself
# build:
# context: "./"
# target: "runtime"
# dockerfile: "./Dockerfile"
container_name: "unifi-voucher-manager"
restart: "unless-stopped"
ports:
- "3000:3000"
# SEE README FOR VALID ENVIRONMENT VARIABLES
# SEE README FOR ENVIRONMENT VARIABLES DOCUMENTATION
environment:
UNIFI_CONTROLLER_URL: "URL to your UniFi controller with protocol (`http://` or `https://`)."
UNIFI_API_KEY: "API Key for your UniFi controller."
UNIFI_HAS_VALID_CERT: "true" # Set to false if your UniFi controller has a self-signed certificate
# To put the environment variables in a `.env` file, uncomment the env_file
# section and comment the environment section.
# env_file:
# - ".env"
UNIFI_HAS_VALID_CERT: "true" # Set to false only if your UniFi controller does not use a valid SSL certificate. Typically, this should remain true when accessing the controller (UNIFI_CONTROLLER_URL) through a reverse proxy or any setup providing trusted SSL certificates (e.g., Let's Encrypt).
WIFI_SSID: "Your guest WiFi SSID" # Optional
WIFI_PASSWORD: "Youw guest WiFi password" # Optional