Docker

Docker is the recommended way to run Bridge on headless servers, Raspberry Pi, NAS devices, and Unraid. Docker handles persistence natively through restart policies.

Docker Run

docker run -d \
  --name printhq-bridge \
  --restart unless-stopped \
  --network host \
  -v bridge-data:/app/data \
  ikyvex/printhq-bridge:latest

Docker Compose

services:
  printhq-bridge:
    image: ikyvex/printhq-bridge:latest
    restart: unless-stopped
    network_mode: host
    volumes:
      - bridge-data:/app/data

volumes:
  bridge-data:

docker compose up -d

Key Settings

--restart unless-stopped

This tells Docker to:

• Restart the container if it crashes
• Restart it when the Docker daemon starts (i.e., after a reboot)
• Keep it running through host sleep/wake cycles
• Only stop if you explicitly run docker stop

--network host

Required. Bridge needs to be on the same network as your printers to discover and communicate with them via mDNS, SSDP, and UDP broadcast. Without host networking, the container is isolated from your LAN and printer discovery won't work.

-v bridge-data:/app/data

Persists Bridge configuration (printers, credentials, settings) across container restarts and upgrades.

Unraid Setup

1. Install the Docker Compose Manager plugin from Community Applications
2. Create a new Docker Compose stack with the YAML config above
3. Make sure the network mode is set to host
4. Map a persistent path or volume for /app/data
5. Start the stack

Alternatively, you can add the container manually in the Unraid Docker UI:

• Image: ikyvex/printhq-bridge:latest
• Network Type: host
• Path: /app/data mapped to a persistent location (e.g., /mnt/user/appdata/printhq-bridge)

Managing the Container

# View logs
docker logs -f printhq-bridge

# Stop
docker stop printhq-bridge

# Start
docker start printhq-bridge

# Restart
docker restart printhq-bridge

# Update to latest version
docker pull ikyvex/printhq-bridge:latest
docker rm -f printhq-bridge
docker run -d \
  --name printhq-bridge \
  --restart unless-stopped \
  --network host \
  -v bridge-data:/app/data \
  ikyvex/printhq-bridge:latest

Environment Variables

Variable	Default	Description
MODE	web	Run mode (web or cli)
PORT	9876	Web UI port
CONFIG_PATH	/app/data/config.json	Configuration file path
SYNC_INTERVAL	10	Sync interval in seconds

Notes

• The web UI is accessible at http://<docker-host-ip>:9876
• The bridge-data volume stores your configuration at /app/data inside the container
• Bridge auto-updates are disabled in Docker — update by pulling the latest image

Docker on macOS / Windows

Docker Desktop on macOS and Windows runs containers inside a VM. Even with --network host, the container can't access your LAN directly, which breaks printer discovery. For best results on macOS and Windows, use the native desktop app instead.