Zebra-Druck-Agent als Docker-Container (CLI)

Überblick

Image docker.zplcloud.com/zplcloud-agent:latest - linux/amd64 + linux/arm64, öffentlich, ohne Login.
Führt zplcloud proxy aus: ausgehendes HTTPS/WebSocket zu api.zplcloud.com; funktioniert hinter NAT und Firewalls.
Drucker im Tab „Remote Printers“ erhalten Jobs, Profile und Probes über den Agenten: LAN (TCP 9100) oder USB (CDC-ACM seriell oder libusb-Druckerklasse).
restart: unless-stopped sorgt für Autostart; optional tägliche Logdatei.

Voraussetzungen

Docker (Desktop, Engine oder Synology Container Manager).
API-Key (Plattform → API).
Drucker im selben LAN (TCP 9100) oder per USB angeschlossen.

docker-compose.agent.yml

ZPLCLOUD_API_KEY und ZPLCLOUD_AGENT setzen:

# docker-compose.agent.yml
services:
  zplcloud-agent:
    image: docker.zplcloud.com/zplcloud-agent:latest
    container_name: zplcloud-agent
    restart: unless-stopped
    environment:
      ZPLCLOUD_API_KEY: "sk_zplcloud_CHANGE_ME"     # API-Tab
      ZPLCLOUD_AGENT: "PI"                           # Name im Tab Remote Printers
      ZPLCLOUD_API_BASE: "https://api.zplcloud.com"  # Backend (ausgehend)
      ZPLCLOUD_VERBOSE: "false"                      # true = SignalR-Trace
      ZPLCLOUD_LOG: "true"                           # schreibt zplcloud-<yyyy-MM-dd>.log
      ZPLCLOUD_LOG_DIR: "logs/zplcloud-logs"
      ZPLCLOUD_TIMEOUT: "5000"
    volumes:
      - ./logs/zplcloud-logs:/logs/zplcloud-logs
      # roher USB-Bus (libusb braucht ihn, um den Zebra-Drucker zu finden)
      - /dev/bus/usb:/dev/bus/usb
    # einfachster USB-Weg (Druckerklasse UND CDC-ACM seriell)
    privileged: true
    # sicherere Alternative: privileged entfernen, Geräte durchreichen + udev-Regel
    # devices:
    #   - "/dev/bus/usb:/dev/bus/usb:rwm"
    #   - "/dev/ttyACM0:/dev/ttyACM0:rwm"
    #   - "/dev/ttyUSB0:/dev/ttyUSB0:rwm"

Die Plattform generiert diese Datei mit Ihren Werten unter ZPL CLI (Docker Compose oder Kommandozeile, privater oder Firmen-Scope).

Umgebungsvariablen

Variable	Pflicht	Bedeutung
ZPLCLOUD_API_KEY	ja	API-Key; authentifiziert den Agenten.
ZPLCLOUD_AGENT	ja	Anzeigename im Tab Remote Printers.
ZPLCLOUD_API_BASE	nein	Basis-URL (Standard https://api.zplcloud.com).
ZPLCLOUD_VERBOSE	nein	`true` = SignalR-Negotiation-/Transport-Trace.
ZPLCLOUD_LOG	nein	`true` = `zplcloud-<yyyy-MM-dd>.log` nach ZPLCLOUD_LOG_DIR schreiben.
ZPLCLOUD_LOG_DIR	nein	Log-Verzeichnis im Container (Bind-Mount ./logs/zplcloud-logs).
ZPLCLOUD_TIMEOUT	nein	Verbindungs-/Lese-Timeout in ms (Standard 5000).

Start, Logs, Update

docker compose -f docker-compose.agent.yml up -d          # starten
docker compose -f docker-compose.agent.yml logs -f zplcloud-agent
docker compose -f docker-compose.agent.yml restart          # z. B. nach API-Key-Wechsel
docker compose -f docker-compose.agent.yml pull && docker compose -f docker-compose.agent.yml up -d   # Update
docker compose -f docker-compose.agent.yml down             # stoppen / entfernen

Plattformen

linux/amd64 - x64 Linux, x64 Synology, Intel-Docker-Hosts, Docker Desktop unter Windows (WSL2).
linux/arm64 - 64-Bit Raspberry Pi OS, ARM-Synology, Apple Silicon.
32-Bit Raspberry Pi: kein Image; nativer Installer (linux-arm) verwenden.

USB-Drucker

privileged: true deckt Druckerklasse (libusb) und CDC-ACM seriell ab.
Ohne privileged: Geräte explizit durchreichen (devices: oben) und udev-Regel anlegen, z. B. GROUP="dialout", MODE="0660" für die Zebra-Vendor-ID.

Fehlersuche

Symptom	Prüfen
Agent nicht online	ZPLCLOUD_API_KEY; `docker compose logs -f`; ZPLCLOUD_VERBOSE=true für den SignalR-Trace.
USB-Drucker nicht gefunden	`privileged: true` oder devices + udev-Regel; `/dev/bus/usb` muss gemountet sein.
TCP 9100 nicht erreichbar	Drucker-IP/Host im Tab Remote Printers; Drucker und Container im selben LAN.