Skip to main content

Debian appliance installation

Nabik uses the existing Frigate container architecture: the production image contains the web interface, Python backend, nginx, go2rtc, detector dependencies, and s6 service supervision. Docker Engine runs on Debian. A separate unprivileged device agent handles enrollment and signed subscription refresh. The licensing admin panel and PostgreSQL service run on the operations server.

Supported installation target​

The installer accepts Debian 12 (Bookworm) and 13 (Trixie), with systemd and an amd64 or arm64 CPU. Each signed release explicitly lists its supported CPU architectures; the initial release preparation defaults to amd64. Acceptance on your exact mini PC is still required before describing it as supported hardware.

Use wired networking, a synchronized system clock, and persistent local storage. The installer requires at least 10 GiB free on the filesystem holding Docker's default data directory. This is an installation floor, not a recording capacity recommendation. Size recording storage from camera bitrates and retention, and size RAM/shared memory from the camera detection streams.

For automatic recovery after load shedding, enable the mini PC's BIOS setting called Restore on AC Power Loss, AC Recovery, or equivalent. Debian cannot turn on a powered-off machine. A UPS is needed for continued recording while power is unavailable. An interrupted recording segment can be lost; automatic restart cannot guarantee footage or database integrity after every power cut.

First installation​

Staff must first deploy the licensing server and publish a prepared release using tested Nabik and device-agent image digests. Replace LICENSE_HOST below with the real hostname supplied by staff. This is a deployment placeholder, not a currently published download URL.

On Debian minimal, log in through a local terminal or SSH. If you use the root account, omit sudo. Install the bootstrap download tools once:

sudo apt-get update
sudo apt-get install -y ca-certificates curl

Download the installer over HTTPS, review it, then run it:

curl --fail --show-error --proto '=https' https://nabik.live/downloads/install.sh -o install.sh
sudo bash install.sh

The installer verifies the signed release manifest and every installation asset, installs Docker Engine from Docker's Debian apt repository when needed, pulls both digest-pinned images, and verifies device enrollment before starting Nabik. Enter the staff-issued single-use token at the hidden prompt. Keep the token out of command arguments, URLs, screenshots, and shell history. Private registry images require a read-only Docker login available to the root account first.

The local installation is /opt/nabik. Open https://MINI_PC_LAN_IP:8971 from another device on the LAN. Nabik retains its existing local administrator onboarding; retrieve the initial generated password with sudo nabikctl logs. If startup logs have scrolled beyond that view, read the full container log with sudo docker compose --project-name nabik -f /opt/nabik/compose.yaml logs nabik. Enroll cameras through the normal Nabik interface. Local administrator accounts are independent of the staff licensing account.

The authenticated web/API port is 8971. WebRTC uses TCP and UDP 8555. The unauthenticated internal API port 5000 and RTSP restreaming port 8554 are not published by default. Restrict LAN access as appropriate. Docker-published ports need Docker-aware firewall rules; do not rely on a host firewall alone to hide them. Do not forward these ports to the public Internet.

Use sudo bash install.sh --check to check the host without installing. This does not verify registry reachability, license activation, drivers, or camera capacity.

Recording storage and hardware​

The default recording path is /opt/nabik/media, mounted inside the container at the existing /media/frigate path. Keep this internal identifier for compatibility. Config, SQLite databases and model caches live under /opt/nabik/config. Device identity lives in agent-state; signed leases live in license-cache; root-owned public trust files live in trust. Container replacement preserves these folders.

To use a dedicated recording disk, mount it persistently using its filesystem UUID in /etc/fstab, create a recording directory there, then install with:

sudo bash install.sh --media-dir /mnt/recordings/nabik

The installer adds a Docker service mount dependency for the storage paths. Avoid optional mount settings that let Docker start against an empty directory when the recording disk is absent. Confirm the correct disk is mounted before installation. Changing this path later requires an explicit data migration.

Put model-specific device mappings and resource settings in /opt/nabik/compose.override.yaml. The installer preserves and uses this file on every rerun. For a tested Intel GPU with /dev/dri present, an example is:

services:
  nabik:
    devices:
      - /dev/dri:/dev/dri
    shm_size: 512mb

Apply the override with sudo nabikctl start. Configure the matching ffmpeg hardware acceleration preset and detector in Nabik separately. Passing the device does not automatically configure acceleration. Follow the existing hardware acceleration guide and installation hardware instructions. NVIDIA and PCIe AI accelerators can require host drivers and a different release image; never guess these settings or enable privileged mode as a generic workaround.

Startup and failure recovery​

Docker is enabled at Debian boot. Both application containers use restart: unless-stopped, so crashes and ordinary power-loss reboots recover without a user login. An intentionally stopped container stays stopped, including after reboot, until you run sudo nabikctl start.

The inherited s6 supervision and application watchdogs retain their existing behavior. A host timer additionally checks Docker health once per minute. It only restarts running services from the managed Nabik project after three consecutive unhealthy observations. Recovery waits at least ten minutes between attempts and allows at most three attempts per service in one hour. Starting, paused, manually stopped, or unrelated containers are never started by this timer.

The device agent health check measures process liveness, independent of licensing server availability. A licensing outage retains the signed cache and bounded network retry behavior. A camera outage or expired subscription does not itself trigger a whole-appliance restart. Persistent faults require diagnosis.

sudo nabikctl status
sudo nabikctl logs
sudo nabikctl restart
sudo nabikctl stop
sudo nabikctl start
sudo journalctl -u nabik-watchdog.service --since today

There are no unattended image upgrades. Containers use the signed release's image digests; startup uses images already downloaded locally. After power returns, local recording can resume without first downloading a new image or contacting GitHub, provided cameras, storage and local networking are available.

Backup, upgrade and rollback​

Before an upgrade, run sudo nabikctl backup. It temporarily stops the running Nabik services to produce a consistent config/database and identity archive, then starts only those services that were running before the backup. Recording pauses during this operation. Root-only archives are written to /opt/nabik/backups. Copy them securely off the mini PC. They contain private device keys and may contain camera credentials. Recordings are excluded and need a separate storage backup.

Download the prepared new installer and rerun it. Both images are pulled before the deployment and trusted keys are replaced. Existing configuration, identity, recordings and hardware overrides are retained. The installer waits for health; if startup fails, it restores the previous image references and public trust bundle. Configuration/database migrations are not automatically reversed.

The last different successful deployment is retained under /opt/nabik/previous. Rerunning the same release does not replace that recovery point. If the prior version is compatible with the current database, run:

sudo nabikctl rollback --confirm

For an incompatible database downgrade, stop Nabik and restore a matching config/database backup first. Restore the archive only to the original appliance identity or an explicitly approved replacement. Review the trusted archive's contents with sudo tar -tzf /PATH/backup.tar.gz, stop services, and restore the needed files into /opt/nabik with their saved permissions/ownership using your backup tool. Keep the pre-restore state for recovery. Do not restore running SQLite databases, copy identity to multiple appliances, or delete the media directory. Then start Nabik and check health, cameras, subscription and playback.

Validation before customer installation​

Automated installer tests exercise real signature/hash verification with simulated Docker and systemd commands. They cover first install, rerun, failed pull, rejected activation, tampering, identity mismatch, preserved overrides, and failed upgrade recovery. Licensing CI can also validate generated Compose using the real Compose plugin. These tests do not certify Debian package installation or hardware.

Before sale, test the actual published image digests on a clean Debian VM and the target mini PC: install, enrollment, multi-camera recording, storage exhaustion, network loss, reboot, power restoration, upgrade, rollback, and backup restoration. Publish the supported hardware and known limitations from those results.

References: Frigate installation, Docker Engine on Debian, and Docker restart policies.