diff --git a/README.md b/README.md index 176c860..8a7a8ff 100644 --- a/README.md +++ b/README.md @@ -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 --- diff --git a/compose.yaml b/compose.yaml index 2df5b5d..9c7719f 100644 --- a/compose.yaml +++ b/compose.yaml @@ -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