chrzimm/unifi-voucher repository overview

⁠UniFi Hotspot Voucher

English version⁠

Erstellt UniFi-Hotspot-Voucher über die offizielle UniFi Network API und zeigt eine druckfertige Gast-WLAN-Karte mit Voucher-Code und WLAN-QR-Code an. Die Karte kann im Browser als PDF gespeichert werden.

Das Image basiert auf Ubuntu 24.04 und enthält Nginx sowie PHP-FPM 8.3.

⁠Funktionen

• Geschützter Admin- und Konfigurationsbereich
• Voucher mit Name, Laufzeit, Einzel- oder Mehrfachnutzung und optionalem Datenlimit
• WLAN-QR-Code für SSID und optionales WLAN-Passwort
• Druckansicht für Papier oder PDF
• Konfiguration über Umgebungsvariablen oder Adminbereich
• Persistente Einstellungen im Volume /var/lib/unifi-voucher

⁠Schnellstart mit Docker Compose

Erstelle eine .env-Datei im Compose-Ordner:

APP_PAGE_PASSWORD=ein-langes-einmaliges-admin-passwort
APP_LANGUAGE=de
APP_API_BASE_URL=https://unifi.example/proxy/network/integration
APP_API_KEY=dein-unifi-network-api-key
APP_SITE_ID=deine-site-id
APP_VERIFY_TLS=true

APP_WIFI_SSID=Gast-WLAN
APP_WIFI_PSK=
APP_LOGO_URL=
APP_WELCOME_TEXT_DE=Willkommen! Wir wünschen Ihnen einen angenehmen Aufenthalt.
APP_WELCOME_TEXT_EN=Welcome! We hope you enjoy your stay.
APP_COLOR_PRIMARY=#1787F7
APP_COLOR_ACCENT=#014FAF
APP_COLOR_BACKGROUND=#f3f6f4

Verwende die zur installierten UniFi-Network-Version passende API-Basisadresse. Sie endet vor /v1/sites/...; die Dokumentation findest du in UniFi Network unter Einstellungen → Integrations.

Compose-Datei:

services:
  unifi-voucher:
    image: chrzimm/unifi-voucher:latest
    container_name: unifi-voucher
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "80:80"
    volumes:
      - voucher-data:/var/lib/unifi-voucher

volumes:
  voucher-data:

Starte den Dienst:

docker compose up -d

Öffne http://<Docker-Host> und melde dich mit APP_PAGE_PASSWORD an. Für den Zugriff über ein nicht vertrauenswürdiges Netzwerk sollte die Anwendung hinter einem HTTPS-Reverse-Proxy betrieben werden.

⁠Konfigurationsvariablen

Die Umgebungsvariablen liefern die Startwerte. Im Adminbereich gespeicherte Werte haben anschließend Vorrang und bleiben im Volume voucher-data erhalten. Sichere dieses Volume regelmäßig. Eine .env-Datei enthält Zugangsdaten und sollte nur für Administratoren lesbar sein; veröffentliche sie niemals im Image oder in einem öffentlichen Repository.

Die Website bietet Deutsch und Englisch über die Sprachwahl oben rechts. Die Auswahl bleibt für die aktuelle Sitzung erhalten und wird auch auf der druckbaren Voucher-Karte verwendet. Die festen Texte liegen in lang/de.php und lang/en.php; individuelle Willkommenstexte können in den Einstellungen für beide Sprachen gepflegt werden.

⁠Entwicklung und Veröffentlichung

Der Gitea-Actions-Workflow unter .gitea/workflows/publish-dockerhub.yml veröffentlicht das Image chrzimm/unifi-voucher auf Docker Hub. Er baut Images für linux/amd64 und linux/arm64; Docker wählt beim Abruf automatisch die passende Architektur. Änderungen auf development starten keinen Build. Zum Veröffentlichen wird ein Pull Request von development nach main erstellt und gemergt. Der Merge nach main startet den Build und aktualisiert die Tags latest und sha-<commit-hash>.

Damit Veröffentlichungen nur über gemergte Pull Requests erfolgen, schütze den Branch main in Gitea unter Repository → Settings → Branches vor direkten Pushes. Der Runner benötigt das Label ubuntu-latest sowie Zugriff auf Docker.

Hinterlege unter Repository → Settings → Actions → Variables/Secrets:

• Variable DOCKERHUB_USERNAME mit dem Docker-Hub-Benutzernamen chrzimm.
• Secret DOCKERHUB_TOKEN mit einem Docker-Hub-Access-Token, das Lese- und Schreibrechte für das Repository hat.

⁠Zertifikate der UniFi-API

Das Image prüft TLS-Zertifikate standardmäßig. Bei einer privaten Zertifizierungsstelle muss deren CA-Zertifikat im Container-Systemzertifikatsspeicher installiert und update-ca-certificates beim Containerstart ausgeführt werden. Nur das Zertifikat in Compose einzubinden reicht nicht aus. Als kurzfristige Alternative kann die Prüfung im Adminbereich deaktiviert werden; das verringert die Verbindungssicherheit.

⁠Logo und QR-Code

Für ein lokales Logo mounte die Bilddatei lesbar in den Webordner, zum Beispiel:

    volumes:
      - voucher-data:/var/lib/unifi-voucher
      - ./kbs1.png:/var/www/html/kbs1.png:ro

Trage dann /kbs1.png als Logo-Pfad ein. Der WLAN-QR-Code wird im Browser erstellt. Dazu lädt der Browser die QR-Bibliothek von cdnjs; für den QR-Code-Inhalt wird kein externer QR-Dienst aufgerufen.

⁠Laufzeit und Module

Das Image enthält PHP-Module und -Funktionen für cURL, mbstring, Sessions, JSON und OpenSSL. PHP-FPM lauscht intern auf 127.0.0.1:9000; Nginx nimmt HTTP auf Container-Port 80 entgegen.

⁠English

⁠UniFi Hotspot Voucher

Creates UniFi hotspot vouchers through the official UniFi Network API and displays a print-ready guest Wi-Fi card with the voucher code and a Wi-Fi QR code. The card can be saved as a PDF from the browser's print dialog.

The image is based on Ubuntu 24.04 and includes Nginx and PHP-FPM 8.3.

⁠Features

• Password-protected admin and configuration area
• Vouchers with a name, duration, single or multiple use, and optional data limit
• Wi-Fi QR code for the SSID and optional Wi-Fi password
• Print layout for paper or PDF
• Configuration through environment variables or the admin area
• Persistent settings in the /var/lib/unifi-voucher volume

⁠Quick start with Docker Compose

Create a .env file in your Compose directory:

APP_PAGE_PASSWORD=choose-a-long-unique-admin-password
APP_LANGUAGE=en
APP_API_BASE_URL=https://unifi.example/proxy/network/integration
APP_API_KEY=your-unifi-network-api-key
APP_SITE_ID=your-site-id
APP_VERIFY_TLS=true

APP_WIFI_SSID=Guest-WiFi
APP_WIFI_PSK=
APP_LOGO_URL=
APP_WELCOME_TEXT_DE=Willkommen! Wir wünschen Ihnen einen angenehmen Aufenthalt.
APP_WELCOME_TEXT_EN=Welcome! We hope you enjoy your stay.
APP_COLOR_PRIMARY=#1787F7
APP_COLOR_ACCENT=#014FAF
APP_COLOR_BACKGROUND=#f3f6f4

Use the API base URL that matches your installed UniFi Network version. It ends before /v1/sites/...; find the version-specific documentation in UniFi Network → Settings → Integrations.

Compose file:

services:
  unifi-voucher:
    image: chrzimm/unifi-voucher:latest
    container_name: unifi-voucher
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "80:80"
    volumes:
      - voucher-data:/var/lib/unifi-voucher

volumes:
  voucher-data:

Start the service:

docker compose up -d

Open http://<docker-host> and sign in with APP_PAGE_PASSWORD. If host port 80 is already in use, change the port mapping, for example to 8080:80, and open http://<docker-host>:8080. For access over an untrusted network, run the app behind an HTTPS reverse proxy.

⁠Environment variables

Environment variables provide the initial values. Values saved in the admin area take precedence afterward and persist in the voucher-data volume. Back up this volume regularly. The .env file contains credentials and should only be readable by administrators; never publish it in the image or a public repository.

The website provides German and English through the language selector in the top right. The selection lasts for the current session and also applies to the printable voucher card. Fixed text is stored in lang/de.php and lang/en.php; custom welcome text can be maintained separately for each language in Settings.

⁠Development and publishing

The Gitea Actions workflow at .gitea/workflows/publish-dockerhub.yml publishes the chrzimm/unifi-voucher image to Docker Hub. It builds images for linux/amd64 and linux/arm64; Docker automatically selects the matching architecture when pulling the image. Changes pushed to development do not start a build. To publish, create and merge a pull request from development into main. The merge to main starts the build and updates the latest and sha-<commit-hash> tags.

To publish only merged changes, protect the main branch from direct pushes in Gitea under Repository → Settings → Branches. The runner needs the ubuntu-latest label and access to Docker.

Add these values under Repository → Settings → Actions → Variables/Secrets:

• Variable DOCKERHUB_USERNAME set to the Docker Hub username chrzimm.
• Secret DOCKERHUB_TOKEN set to a Docker Hub access token with read and write access to the repository.

⁠UniFi API certificates

TLS certificate verification is enabled by default. If your UniFi API uses a private certificate authority, install its CA certificate in the container's system trust store and run update-ca-certificates when the container starts. Mounting the certificate in Compose alone is not sufficient. Disabling verification in the admin area is a temporary alternative, but it reduces connection security.

⁠Logo and QR code

To use a local logo, mount the image read-only into the web root, for example:

    volumes:
      - voucher-data:/var/lib/unifi-voucher
      - ./kbs1.png:/var/www/html/kbs1.png:ro

Then set /kbs1.png as the logo path. The Wi-Fi QR code is generated in the browser. The browser downloads the QR library from cdnjs; QR contents are not sent to an external QR-generation service.

⁠Runtime and PHP modules

The image includes PHP support for cURL, mbstring, sessions, JSON, and OpenSSL. PHP-FPM listens internally on 127.0.0.1:9000; Nginx accepts HTTP on container port 80.