Installation with Docker

This guide explains how to install UHPPOTE Desk with Docker on a server or NAS and how to configure it for your network. Nothing needs to be compiled: you use the ready-made image.

Image

To stay on a release instead of following main, use a version tag: ghcr.io/alexbn71/uhppote-desk:1 receives the 1.x releases (new features and fixes, no breaking changes), :1.0.0 never changes. The releases and their notes are on the releases page and in CHANGELOG.md.

The image is built and verified by GitHub Actions on every change: tests, a trial start of the container, publication.

Network requirements (important)

The server and the controllers communicate over UDP. This requires a few conditions:

1. The container must use host networking (network_mode: host / --network host). With Docker's bridge network the controller discovery (broadcast) never leaves the container and the events the controllers send to the server never arrive. Mapping ports is not enough.
2. The server and the controllers must be on the same local network, i.e. the same subnet, for automatic discovery to work. If the controllers are on another subnet it still works, but their IP addresses must be entered manually in the app.
3. Firewall: inbound UDP port 60001 (or the one set in UHPPOTE_LISTEN) and the TCP port of the web interface must be open.
4. Security: the controller protocol is neither authenticated nor encrypted. Put controllers and server on a separate network (VLAN) and make the web interface reachable only from the local network or through a VPN.

Environment variables

In the examples the server has IP 192.168.1.10 and the controllers are on the 192.168.1.0/24 subnet. Replace them with your own values.

Required

Recommended

Optional

Home Assistant (MQTT)

All optional: without MQTT_URL the integration is off. Details in HOME-ASSISTANT.md.

Data folder owner

Already set in the image (do not change)

Installation with Docker Compose

Uses docker/docker-compose.yml and docker/.env.example:

git clone https://github.com/alexbn71/UHPPOTE-Desk.git
cd UHPPOTE-Desk/docker
cp .env.example .env
# edit .env: at least UHPPOTE_LISTENER_PUBLIC and UHPPOTE_BROADCAST
docker compose up -d
docker logs uhppote-desk          # admin password, if ADMIN_PASSWORD is not set

Minimal docker-compose.yml, if you don't clone the repository:

services:
  uhppote-desk:
    image: ghcr.io/alexbn71/uhppote-desk:latest
    container_name: uhppote-desk
    restart: unless-stopped
    network_mode: host
    environment:
      UHPPOTE_LISTENER_PUBLIC: 192.168.1.10:60001
      UHPPOTE_BROADCAST: 192.168.1.255:60000
      TZ: Europe/Rome
    volumes:
      - ./data:/data

A host folder (./data above) can be used directly: it is created if missing and the database is initialised on first start. See Data folder and permissions.

Data folder and permissions

/data holds the SQLite database (uhppote-desk.sqlite), daily backups, photos and test reports. It can be a Docker named volume or any folder of the host (bind mount).

• First start: if the folder or the database does not exist, they are created and the database schema is initialised (log: no database found in /data: creating a new one). On later starts the existing database is reused and upgraded if needed (log: using database /data/uhppote-desk.sqlite).
• Ownership: the container starts as root only to prepare the folder: it creates it if missing and, when needed, changes its owner to PUID:PGID. It then runs the application as that user, never as root. Set PUID/PGID to the owner you want on the host (e.g. your user, id -u / id -g; on Unraid 99/100).
• Starting with --user (or user: in compose) skips that preparation: the folder must then already be writable by that user. If it is not, the container stops with a message like the data directory /data is not writable by the process (uid 1000, gid 1000) and the fix to apply.
• Running the hardware test tool with docker exec uses root by default; the next start restores the correct owner automatically, or use docker exec --user <PUID>:<PGID> ….

Installation with docker run

docker run -d --name uhppote-desk --restart unless-stopped \
  --network host \
  -e UHPPOTE_LISTENER_PUBLIC=192.168.1.10:60001 \
  -e UHPPOTE_BROADCAST=192.168.1.255:60000 \
  -e TZ=Europe/Rome \
  -v uhppote-desk-data:/data \
  ghcr.io/alexbn71/uhppote-desk:latest

With a host folder instead of a named volume: -v /srv/uhppote-desk:/data -e PUID=$(id -u) -e PGID=$(id -g).

Installation on Unraid

1. From the Unraid terminal, download the template:

   wget -O /boot/config/plugins/dockerMan/templates-user/my-uhppote-desk.xml \
     https://raw.githubusercontent.com/alexbn71/UHPPOTE-Desk/main/docker/unraid/uhppote-desk.xml
   

2. Docker → Add Container → Template: uhppote-desk.
3. Fill in at least Event destination (UHPPOTE_LISTENER_PUBLIC) and Discovery broadcast (UHPPOTE_BROADCAST), and check that the Web port is free. The other variables are under Show more settings.
4. The template already sets:
   • host networking;
   • data folder /mnt/user/appdata/uhppote-desk mounted on /data;
   • PUID=99, PGID=100 (nobody:users), the standard owner of appdata;
   • the image tag :1 (stable releases); change it to :latest to follow the development version.
5. Apply, then open the WebUI from the container icon.

Support for Unraid: forum thread. The template is also published in alexbn71/unraid-templates for Community Applications.

Other NAS systems

• Synology (Container Manager): create a Project with the example docker-compose.yml. network_mode: host is supported.
• QNAP (Container Station): create an application from the example compose file, or choose Host networking when creating the container manually.

On both, make sure the data folder is writable by the container user (see the note in the Docker Compose section).

First start

1. Open http://<server-IP>:<HTTP_PORT> and log in as admin: with ADMIN_PASSWORD set use that password; otherwise use the one printed in the container log (Created user 'admin' with temporary password: …), and you are asked for a new password immediately.
2. Controllers → Search network: the controllers reachable by broadcast are listed with serial number, IP and firmware. Add registers them in the app. The interface language can be changed from the language menu in the header.
3. As soon as a controller is online, the app sends it the event destination (UHPPOTE_LISTENER_PUBLIC) and synchronises its clock. If a controller comes online without any card while the database expects some (factory reset, replaced controller), the app synchronises it completely by itself; any other difference is only reported in the log, and Synchronisation aligns it. You can check this in Controllers → (controller) → Diagnostics, "Event listener" entry.

Commissioning from the container

The hardware test suite is included in the image:

docker exec -it uhppote-desk node hwtest/cli.js --help
docker exec -it uhppote-desk node hwtest/cli.js --serial <S/N> --ip <controller IP> --level 0,1
docker exec -it uhppote-desk node hwtest/cli.js --serial <S/N> --ip <controller IP> --level 5   # full deployment check

Reports are saved in /data/reports. The test levels are described in the README.

Trying the app without a controller (simulator)

The image also contains a simulated 4-door UT0311-L04 controller. Run it inside the running container (it shares the host network, so the app sees it like a real controller on the LAN):

docker exec -it uhppote-desk node hwtest/devsim.js              # interactive: keyboard commands
docker exec -d  uhppote-desk node hwtest/devsim.js --auto 10    # background: a random swipe every 10 s

• Then use Controllers → Search network and add controller 405419896. If the search finds nothing, add it manually with the server's LAN IP.
• The simulated controller reports the server's IP on the UHPPOTE_BROADCAST subnet (or the first LAN address). Use --address <IP> to force it, and --serial <n> to change the serial number.
• Interactive commands: s <card> [door] swipe, o <door> / c <door> door sensor open/closed, b <door> exit button, l cards, e last events, off / on simulate a cable unplugged, q quit.
• It listens on UDP/TCP port 60000 of the host: stop it before connecting a real controller on the same host, and do not run it twice.
• Like a real controller it keeps its memory (cards, time profiles, settings, events) when it stops or the container restarts: it is saved in /data/devsim-<serial>.json. Run it with --fresh to start with an empty memory (as after a factory reset).
• Restarting the container also stops the simulator: start it again with the same command.
• To stop a background simulator: docker restart uhppote-desk.

Updates and backups

• Update: docker compose pull && docker compose up -d. On Unraid: Check for updates → Update. The database schema is upgraded automatically at startup.
• Automatic backup: every day at BACKUP_HOUR into /data/backups, or manually from System → Create backup now. For a complete backup, copy the data folder.
• Before a controller factory reset, its cards are saved to /data/backups/cards-<serial>-<date>.json.

Troubleshooting