zplcloud.com/docs

Was ist der Docker-Agent und wofür ist er gut?

Der zplcloud-agent ist die zplcloud-CLI als vorbereiteter Container. Er läuft auf einem Rechner in der Nähe deiner Zebra-Drucker und verbindet sich ausgehend mit api.zplcloud.com - ähnlich wie TeamViewer. Danach kannst du im zplCloud-„Remote Printers“-Tab Drucker anlegen und Druckaufträge, Profile und Probes über den Agenten an die Drucker im lokalen LAN (TCP 9100) oder an USB-Drucker weitergeben.

Keine eingehenden Ports - nur eine ausgehende HTTPS/WebSocket-Verbindung, funktioniert hinter NAT und Firewalls.
Ein Container statt Dateipfad - ideal für Raspberry Pi (64-bit), Synology, Intel/Apple-Silicon-Mac mit Docker Desktop.
Mehrarchitektur-Image - linux/amd64 + linux/arm64, öffentlich, ohne Login.
USB-Drucker - ZPL über USB-virtuelle-COM-Ports (CDC-ACM) oder libusb (Drucker-Klasse).
Autostart & Logs - restart: unless-stopped, Tages-Logdatei optional.

Voraussetzungen

Docker (Desktop, Docker Engine oder Synology-Container-Manager).
Ein API-Key aus dem zplCloud-API-Tab.
Drucker im selben LAN erreichbar (TCP 9100) oder per USB angeschlossen.

docker-compose.agent.yml

Lade die Datei herunter (oder kopiere sie) und passe ZPLCLOUD_API_KEY und ZPLCLOUD_AGENT an:

# 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 Remote-Printers-Tab
      ZPLCLOUD_API_BASE: "https://api.zplcloud.com"  # öffentliches Backend (ausgehend)
      ZPLCLOUD_VERBOSE: "false"                      # true = SignalR/Debug-Trace
      ZPLCLOUD_LOG: "true"                           # zplcloud-<yyyy-MM-dd>.log schreiben
      ZPLCLOUD_LOG_DIR: "/logs"
      ZPLCLOUD_TIMEOUT: "5000"
    volumes:
      - agent-logs:/logs
      # Raw-USB-Bus (nötig für libusb, um den Zebra-Drucker zu erkennen/anzusprechen)
      - /dev/bus/usb:/dev/bus/usb
    # Einfachster USB-Weg (funktioniert für Drucker-Klasse UND CDC-ACM-Serial)
    privileged: true
    # Sicherere Alternative (privileged entfernen, dann udev-Regel verwenden):
    # devices:
    #   - "/dev/bus/usb:/dev/bus/usb:rwm"
    #   - "/dev/ttyACM0:/dev/ttyACM0:rwm"
    #   - "/dev/ttyUSB0:/dev/ttyUSB0:rwm"

volumes:
  agent-logs:

Umgebungsvariablen (alle Parameter)

Variable	Pflicht	Bedeutung
ZPLCLOUD_API_KEY	ja	API-Key aus dem zplCloud-API-Tab; authentifiziert den Agenten am Backend.
ZPLCLOUD_AGENT	ja	Anzeigename im „Remote Printers“-Tab (frei wählbar, z. B. „Warehouse Berlin“, „PI“).
ZPLCLOUD_API_BASE	nein	Basis-URL (Standard: https://api.zplcloud.com).
ZPLCLOUD_VERBOSE	nein	`true` = SignalR-Negotiation-/Transport-Trace (Fehlersuche).
ZPLCLOUD_LOG	nein	`true` = schreibt `zplcloud-<yyyy-MM-dd>.log` in ZPLCLOUD_LOG_DIR.
ZPLCLOUD_LOG_DIR	nein	Log-Verzeichnis im Container (z. B. /logs, per Volume gemountet).
ZPLCLOUD_TIMEOUT	nein	Connect-/Read-Timeout in ms (Standard: 5000).

Starten & verwalten

# Starten (hintergrund, Autostart)
docker compose -f docker-compose.agent.yml up -d

# Logs live verfolgen
docker compose -f docker-compose.agent.yml logs -f zplcloud-agent

# Neustart (z. B. nach API-Key-Wechsel)
docker compose -f docker-compose.agent.yml restart

# Neuestes Image ziehen + neu starten (Update)
docker compose -f docker-compose.agent.yml pull
docker compose -f docker-compose.agent.yml up -d

# Stoppen / Entfernen
docker compose -f docker-compose.agent.yml down

Unterstützte Plattformen

linux/amd64 - x64-Linux, x64-Synology, Intel-Docker-Hosts, Windows-Docker (WSL2).
linux/arm64 - 64-bit Raspberry Pi (Pi OS 64-bit), ARM-Synology, Apple-Silicon-Docker.
32-bit Raspberry Pi: kein 32-bit-ARM-Image → stattdessen den direkten Installer verwenden.

USB-Drucker im Container

Einfachster Weg: privileged: true - funktioniert für die USB-Drucker-Klasse (libusb) und CDC-ACM-Serial.
Sicherer: privileged entfernen und die Geräte gezielt mounten (devices: oben, auskommentiert) plus eine udev-Regel, z. B. GROUP="dialout", MODE="0660" für den Zebra-Drucker.

Troubleshooting

Symptom	Lösung
Agent erscheint nicht online	ZPLCLOUD_API_KEY prüfen, Logs ansehen (`docker compose logs -f`), ZPLCLOUD_VERBOSE=true für Trace.
USB-Drucker nicht erreichbar	`privileged: true` setzen oder Geräte + udev-Regel konfigurieren; `/dev/bus/usb` muss gemountet sein.
TCP 9100 nicht erreichbar	Drucker-IP/-Host im Remote-Printers-Tab prüfen; Drucker und Container müssen im selben LAN sein.