Druckplattform und lokalen Agenten einrichten

Workspace verwaltet Vorlagen, Druckregeln und Aufträge zentral. Der lokale nucleus-print-agent holt fertig gerenderte Artefakte über HTTPS ab und übergibt sie an Drucker im lokalen Netz. Stampede wird für diesen Ablauf nicht mehr benötigt.

Diese Anleitung führt durch eine Linux-Installation. Am Ende sind Workspace, Agent, Station und Drucker miteinander verbunden, ohne dass ein eingehender Zugang zum lokalen Netz geöffnet werden muss.

Vor dem Start

Sie benötigen:

• einen Linux-Rechner, der Workspace per HTTPS und die lokalen Drucker erreicht;
• ein aktuelles nucli mit einem angemeldeten Tenant-Profil;
• das zur Workspace-Version passende Quellpaket des Agenten sowie Rust und Cargo;
• Root-Rechte für Benutzer, Verzeichnisse und den systemd-Dienst;
• eine vorhandene CUPS-/IPP-Warteschlange oder Adresse für Raw TCP;
• ein TLS-Zertifikat samt privatem Schlüssel für die lokale Administrationsoberfläche.

Prüfen Sie zuerst Tenant, Berechtigungen und den aktuellen Druckstatus:

nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> printing status
nucli skills show printing

printing status nennt fehlende Formate, Regeln, Agenten oder Stationen. Die Befehle von nucli printing arbeiten immer über die authentisierte, tenantgebundene Workspace-API.

1. Agenten bauen und Systemkonto anlegen

Entpacken Sie das versionsgebundene Quellpaket in ein eigenes Arbeitsverzeichnis und führen Sie den Build dort aus:

cd <entpacktes-agent-quellpaket>
cargo build --release --locked

Installieren Sie anschließend Systemkonto, Binary, Service-Unit und Verzeichnisse:

sudo useradd --system --home-dir /var/lib/nucleus-print-agent \
  --shell /usr/sbin/nologin nucleus-print-agent
sudo install -m 0755 \
  target/release/nucleus-print-agent \
  /usr/bin/nucleus-print-agent
sudo install -m 0644 \
  nucleus-print-agent.service \
  /etc/systemd/system/nucleus-print-agent.service
sudo install -d -o root -g nucleus-print-agent -m 0750 \
  /etc/nucleus-print-agent
sudo install -d -o nucleus-print-agent -g nucleus-print-agent -m 0750 \
  /var/lib/nucleus-print-agent

Falls das Systemkonto bereits existiert, überspringen Sie nur den Befehl useradd. Ändern Sie keine vorhandene UID oder Gruppenzuordnung.

2. Agenten sicher in Workspace registrieren

Legen Sie als normaler Benutzer ein privates Übergabeverzeichnis an. Der Zielpfad für das Token muss neu sein:

install -d -m 0700 "$HOME/.config/nucleus-print-agent-bootstrap"
nucli --tenant <tenant> printing agent register \
  --name <standort-agent> \
  --token-output "$HOME/.config/nucleus-print-agent-bootstrap/agent.token"

nucli zeigt Agenten-ID und Dateipfad, aber niemals das Token. Die Datei entsteht mit Modus 0600; eine vorhandene Datei wird nicht überschrieben. Notieren Sie die ausgegebene Agenten-ID für die Konfiguration.

Installieren Sie das Token für das Systemkonto:

sudo install -o nucleus-print-agent -g nucleus-print-agent -m 0600 \
  "$HOME/.config/nucleus-print-agent-bootstrap/agent.token" \
  /etc/nucleus-print-agent/agent.token

Geht die Übergabedatei verloren oder war sie ungeschützt, registrieren Sie keinen zweiten Agenten. Erzeugen Sie nach bewusster Freigabe ein neues Token mit folgendem Befehl.

nucli --tenant <tenant> printing agent rotate-token <agent-id> \
  --token-output "$HOME/.config/nucleus-print-agent-bootstrap/agent-token-neu"

Die Rotation macht das vorherige Token ungültig.

3. Lokales Administrationspasswort und TLS einrichten

Erzeugen Sie den Passwort-Hash, ohne das Passwort in ein Befehlsargument zu schreiben:

systemd-ask-password "Lokales Administrationspasswort für den Print-Agenten" \
  | nucleus-print-agent hash-password

Installieren Sie ein Zertifikat, dem Ihre Administrationsgeräte vertrauen, und den zugehörigen privaten Schlüssel. Der Schlüssel darf nur für das Systemkonto lesbar sein:

sudo install -o root -g root -m 0644 <tls-zertifikat> \
  /etc/nucleus-print-agent/tls.crt
sudo install -o nucleus-print-agent -g nucleus-print-agent -m 0600 \
  <privater-tls-schluessel> /etc/nucleus-print-agent/tls.key

Die lokale Oberfläche ist standardmäßig an 127.0.0.1 gebunden. Binden Sie sie nur dann an eine andere lokale Adresse, wenn sie aus einem vertrauenswürdigen Administrationsnetz erreichbar sein muss. Stellen Sie sie niemals öffentlich bereit.

4. Station und Druckziele konfigurieren

Kopieren Sie die Beispielkonfiguration geschützt in das Übergabeverzeichnis und bearbeiten Sie zunächst diese Kopie:

install -m 0600 config.example.yaml \
  "$HOME/.config/nucleus-print-agent-bootstrap/config.yaml"

Tragen Sie mindestens diese Werte ein:

• cloud.baseUrl: die HTTPS-Adresse von Workspace;
• cloud.agentId: die bei der Registrierung ausgegebene Agenten-ID;
• adminPasswordHash: den erzeugten Argon2-Hash;
• stations[].key: einen stabilen Schlüssel für den Arbeitsplatz;
• targets[].key: das semantische Ziel, etwa variant.label oder shipping.label;
• outputFormat und bei ZPL die passende dpi-Zahl;
• je Ziel entweder eine CUPS-Warteschlange oder eine lokale Raw-TCP-Adresse.

Installieren Sie die fertige Datei geschützt:

sudo install -o nucleus-print-agent -g nucleus-print-agent -m 0600 \
  "$HOME/.config/nucleus-print-agent-bootstrap/config.yaml" \
  /etc/nucleus-print-agent/config.yaml

Der Agent unterstützt unter Linux zwei lokale Treiber:

• cups übergibt PDF regulär und Druckersprachen im Raw-Modus an eine CUPS-/IPP-Warteschlange. Medium, Schacht und weitere Optionen bleiben lokal.
• raw_tcp sendet das Artefakt direkt an eine lokale TCP-Adresse, üblicherweise Port 9100.

Workspace erhält weder Warteschlangennamen noch Druckeradressen. Die Cloud kennt nur Station, semantisches Ziel, Ausgabeformat, Auflösung, Priorität und Zustand.

5. Konfiguration prüfen und Dienst starten

Prüfen Sie die Installation mit demselben Systemkonto, das später den Dienst ausführt:

sudo -u nucleus-print-agent nucleus-print-agent check \
  --config /etc/nucleus-print-agent/config.yaml

Der Check validiert Konfiguration, Passwort-Hash, Token-Zuordnung sowie TLS-Dateien. Er baut keine Netzwerkverbindung auf und druckt nichts. Starten Sie den Dienst erst nach der Meldung Configuration valid:

sudo systemctl daemon-reload
sudo systemctl enable --now nucleus-print-agent.service
sudo journalctl -u nucleus-print-agent.service -n 50 --no-pager

Löschen Sie die lokale Übergabekopie des Tokens erst, nachdem der Check mit der installierten Datei erfolgreich war:

rm "$HOME/.config/nucleus-print-agent-bootstrap/agent.token"

6. Verbindung und Warehouse-Zuordnung prüfen

Sobald der Dienst läuft, meldet er Stationen und Fähigkeiten an Workspace:

nucli --tenant <tenant> printing status
nucli --tenant <tenant> printing list stations

Ordnen Sie eine Station bei Bedarf einem Warehouse zu:

nucli --tenant <tenant> printing station assign <station-id> \
  --warehouse <warehouse-id>

Die Einrichtung ist betriebsbereit, wenn printing status mindestens ein renderbares Format, eine aktive Druckregel, einen aktiven Agenten sowie eine erreichbare Station mit erreichbarer Fähigkeit meldet.

Vorlagen druckersprachenneutral pflegen

Eine logische Vorlage beschreibt Zweck, Datenvertrag und Abmessungen. Darunter liegen getrennte Renderings. Jedes Rendering legt Inhaltssprache, Ausgabeformat und gegebenenfalls die Auflösung fest und besitzt unveränderliche Revisionen.

Es gibt bewusst keinen universellen Übersetzer zwischen Druckersprachen. Für dieselbe Vorlage können Sie ein ZPL-Rendering mit 203 dpi und später ein eigenes Rendering für eine weitere Druckersprache pflegen. Ein Formatname macht ZPL-Quelltext nicht portabel. Jede zusätzliche Sprache benötigt einen passenden Validator und Renderer in Workspace.

Legen Sie unter Lagerverwaltung > Drucken zuerst die logische Vorlage an. Fügen Sie danach ein Rendering hinzu und wählen Sie Inhaltssprache, Ausgabeformat und Auflösung. ZPL-Platzhalter sind nur innerhalb von ^FD-Feldern erlaubt. Dynamische Werte können daher keine Steuerbefehle einschleusen. Persistente Konfigurations-, Netzwerk-, Speicher- und Mengenbefehle bleiben gesperrt; die Kopienzahl gehört zum Druckauftrag.

Eine Druckregel verbindet Quelltyp, Vorlage, semantisches Ziel, Sprache und Standardmenge. Regeln können tenantweit oder für ein Warehouse gelten. Bereits erzeugte Versandlabel lassen sich als unveränderte PDF-Artefakte über denselben Agenten ausgeben.

Fehler gezielt eingrenzen

Aktuelle Grenzen

• Der mitgelieferte Agent unterstützt derzeit Linux mit CUPS/IPP und Raw TCP.
• Ein Windows-Dienst und Windows-Spooler sind vorgesehen, aber noch nicht implementiert. Sie werden hinter derselben lokalen Treibergrenze ergänzt; Cloud-API und Vorlagenmodell bleiben unverändert.
• Eine Bildvorschau oder ein Drag-and-drop-Designer gehört nicht zum aktuellen Umfang.
• Der Status submitted bestätigt die Annahme durch CUPS oder Raw TCP. completed bleibt Treibern mit belastbarer Abschlussbestätigung vorbehalten.