🐳 Agent in Docker

Mit Docker installierst du den Agenten auf jedem Rechner, ob es ein eigenes Paket dafür gibt oder nicht. Ist dein Rechner ein Synology, ein QNAP, ein TrueNAS, ein Windows-PC oder Home Assistant, schau vorher auf seine Seite unter Der lokale Agent: mit dem Paket hast du weniger Schritte.

---

Was du brauchst

• Einen Rechner in der Werkstatt, der immer eingeschaltet ist: ein NAS, ein Mini-PC, der PC der Werkstatt, ein Raspberry Pi oder ein Server, den du ohnehin schon hast.
• Docker mit Docker Compose, oder Portainer, also Docker mit Oberfläche.
• Dass er im selben Netzwerk wie die Drucker steht, damit er sie von allein findet.

Er ist genügsam: Er braucht keinen leistungsstarken Rechner, und das Manifest begrenzt ihn auf 512 MB Arbeitsspeicher.

Unter Docker Desktop (Windows und Mac) gibt es keine automatische Erkennung. Dort läuft Docker in einer virtuellen Maschine, die das Netzwerk des Rechners nicht sieht, deshalb werden die Drucker per IP hinzugefügt. Sie funktionieren exakt gleich; es ist beim Anlegen nur ein Schritt mehr. Unter Windows hat der Windows-Installer diese Einschränkung nicht.

---

In BolloPrint anlegen

1. Geh zu Einstellungen → Drucker und öffne den Tab Lokaler Agent.
2. Drück auf Neuer Agent. Wähl unter Wo installierst du ihn? bei Mit einem Container die Option Docker.
3. Gib ihm einen Namen, den du wiedererkennst. Besser wo er steht als was er ist: „Erdgeschoss“, „Halle 2“.
4. Drück auf Agent anlegen.
5. Es erscheint das Manifest, in dem der Code des Agenten und seine Identität schon eingetragen sind. Lass den Tab Docker Compose gewählt und drück auf Kopieren. Es gibt nichts zu ersetzen.
6. Wenn das Manifest an einem sicheren Ort gespeichert ist, drück auf Speichern, um das Fenster zu schließen.

So sieht das Manifest aus. In deinem stehen deine Schlüssel statt CHANGE_ME und die gerade passende Agentenversion statt YYYY:

services:
  bolloprint-agent:
    image: ghcr.io/bolloprint/bolloprint-agent:YYYY
    container_name: bolloprint_agent
    restart: unless-stopped
    network_mode: host
    mem_limit: 512m
    pids_limit: 512
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      BP_AGENT_CODE: CHANGE_ME
      BP_AGENT_INSTANCE_ID: CHANGE_ME
      BP_PLATFORM: docker
    volumes:
      - identity:/var/lib/bolloprint

volumes:
  identity:
    name: bolloprint_agent_identity

Kopier nicht dieses hier: kopier immer deins vom Bildschirm in BolloPrint, denn dort stehen deine Schlüssel.

Zwei Zeilen, die du verstehen solltest:

• BP_AGENT_CODE und BP_AGENT_INSTANCE_ID sind die Schlüssel des Agenten: wer er ist und für welche Werkstatt er arbeitet. Behandle sie wie ein Passwort.
• network_mode: host sorgt dafür, dass der Agent dein Netzwerk sieht, um die Drucker zu finden. Es öffnet keinen Port.

---

Auf deinem Rechner starten

Das Manifest geht unverändert hinein, ohne etwas anzufassen. Wähl die Variante, die du nutzt.

Docker Compose

1. Leg einen Ordner für den Agenten an, zum Beispiel bolloprint-agent.
2. Speicher darin das Manifest als docker-compose.yml.
3. Starte ihn aus diesem Ordner:

docker compose up -d

Portainer

1. Geh zu Stacks → Add stack und gib ihm einen Namen, zum Beispiel bolloprint-agent.
2. Füg im Web editor das Manifest unverändert ein.
3. Drück auf Deploy the stack.

Die Container-Verwaltung deines NAS

Bringt dein NAS eine eigene Container-Verwaltung mit (zum Beispiel den Container Manager von Synology), leg ein neues Projekt an, füg das Manifest als dessen docker-compose.yml ein und starte es. Das ist dasselbe wie Docker Compose, nur mit Oberfläche.

---

Prüfen, ob es funktioniert

In weniger als einer Minute wechselt der Agent im Tab Lokaler Agent von Nicht installiert auf Online, mit dem Namen des Rechners, auf dem er läuft, und seiner Version. Er fragt nicht nach einer Freigabe: diese Installation ist bereits freigegeben.

Erscheint er nicht, schau in sein Protokoll auf dem Rechner, auf dem er läuft:

docker logs bolloprint_agent --tail 50

Was passiert	Was zu prüfen ist
Er erscheint nie	Wurde das ganze Manifest ohne Änderungen eingefügt? Kommt der Rechner ins Internet? Blockiert eine Firewall den ausgehenden Verkehr?
Er erscheint, verlangt aber eine Freigabe	Das Manifest enthält kein BP_AGENT_INSTANCE_ID (es wurde von Hand bearbeitet oder ist älter). Erzeuge die Schlüssel neu und roll das neue Manifest unverändert aus.
Er ist online, findet aber keine Drucker	Steht er in einem anderen Netzwerk als die Drucker, oder nutzt du Docker Desktop, ist das zu erwarten: füg sie mit Per IP hinzufügen hinzu.

Ist der Agent online, ist der nächste Schritt, deine Drucker zu verbinden: das findest du unter Drucker im lokalen Netzwerk.

---

Aktualisieren

Seit Version 2026.1.1 aktualisiert sich der Agent von allein: Erscheint eine neue Version, lädt er sie herunter, prüft, dass sie von uns stammt, und startet mit ihr neu. Das tut er nie, während einer seiner Drucker druckt. Du musst deine Datei nicht anfassen.

Von Hand ist es nur nötig, wenn BolloPrint dich darum bittet (zum Beispiel bei einem vor längerer Zeit installierten Agenten mit einer Version von vor der automatischen Aktualisierung). Du siehst das so:

• Über den Tabs von Einstellungen → Drucker ein Hinweis mit dem Namen deines Agenten: „‚Erdgeschoss‘ nutzt Version XXXX. Version YYYY ist verfügbar“, mit dem Button So aktualisierst du.
• Im Tab Lokaler Agent die Versionsnummer dieses Agenten in Orange. In Rot wird diese Version nicht mehr unterstützt, und du solltest so schnell wie möglich aktualisieren.

Was sich ändert

Es ändert sich nur die Zeile image:, und darin nur die Version, also das, was nach dem Doppelpunkt steht. Alles andere bleibt exakt gleich: die Schlüssel, das Volume und die restliche Konfiguration.

Die passende Version findest du im Tab Bereitstellung deines Agenten (Menü ⋮ → Bearbeiten): es ist die in der Zeile image:.

Vorher

    image: ghcr.io/bolloprint/bolloprint-agent:XXXX

Nachher

    image: ghcr.io/bolloprint/bolloprint-agent:YYYY

Mit Docker Compose

1. Öffne die docker-compose.yml des Agenten und ändere die Version in der Zeile image:.
2. Lad aus dem Ordner dieser Datei die neue Version herunter und starte ihn neu:

docker compose pull
docker compose up -d

Docker ersetzt den Container durch einen neuen mit derselben Konfiguration und demselben Volume.

Mit Portainer

1. Geh zu Stacks und öffne den Stack des Agenten.
2. Drück auf Editor und ändere die Version in der Zeile image:.
3. Aktivier Re-pull image and redeploy (oder Pull latest image, je nach deiner Portainer-Version) und drück auf Update the stack.

Prüfen, ob es geklappt hat

In weniger als einer Minute erscheint der Agent wieder als Online, mit der neuen Version und ohne Warnfarbe. Der Hinweis über den Tabs verschwindet von selbst. Während der Container neu startet, können die Drucker ein paar Sekunden als Getrennt erscheinen: sie kommen von allein zurück, und laufende Drucke setzen sich an der Maschine fort.

Und wenn die neue Version Probleme macht? Setz die vorherige Version wieder in die Zeile image: und roll genauso aus. Stell danach eine Anfrage beim Support, damit wir es uns ansehen.

---

Auf einen anderen Rechner umziehen

Die Identität des Agenten steht im Manifest (BP_AGENT_INSTANCE_ID), dieselbe Datei auf einer anderen Maschine gestartet ist also derselbe Agent: mit seinen Druckern, ohne Freigabe und ohne dass du etwas extra kopieren musst.

1. Stopp ihn auf dem alten Rechner: docker compose down in seinem Ordner, oder lösch den Stack in Portainer.
2. Bring die docker-compose.yml auf den neuen Rechner und starte sie dort mit docker compose up -d.

Stopp den alten, bevor du den neuen startest: zwei Rechner mit denselben Schlüsseln gleichzeitig kommen sich bei der Verbindung in die Quere.

Ist dein Manifest älter und hat keine Zeile BP_AGENT_INSTANCE_ID, erscheint der Agent beim Start auf einem anderen Rechner als Installation, die auf Freigabe wartet (weiter unten). Gib sie frei, und er bleibt derselbe Agent, mit seinem ganzen Verlauf.

Du hast die Datei nicht mehr? Dann erzeuge die Schlüssel neu und roll das neue Manifest auf dem neuen Rechner aus.

---

Die Schlüssel neu erzeugen

Im Fenster des Agenten (Menü ⋮ → Bearbeiten), Tab Bereitstellung, erzeugt Schlüssel neu erzeugen einen neuen Code und eine neue Identität und zeigt dir das Manifest damit.

Nutze es in zwei Fällen:

• Du hast das Manifest verloren und musst den Agenten erneut ausrollen.
• Du glaubst, dass jemand deine Schlüssel hat, zum Beispiel weil eine Installation auftaucht, die nicht von dir ist.

Es trennt den Agenten sofort: Der vorherige Code und die vorherige Identität gelten nicht mehr, sobald du den Button drückst, und der Agent bleibt getrennt, bis du ihn mit dem neuen Manifest erneut ausrollst. Hier fügst du das Manifest tatsächlich ganz ein, statt des alten, und startest ihn neu (docker compose up -d, oder Update the stack in Portainer). Das Volume bleibt, wie es ist.

Hat sich der Agent nie verbunden (er steht auf Nicht installiert), trennt das Neu-Erzeugen nichts.

Zum Aktualisieren musst du nichts neu erzeugen. Es reicht, die Version des Images zu ändern.

---

Installationen freigeben

Die Installation aus dem Manifest, das du kopiert hast, kommt direkt herein. Jede andere Installation, die denselben Code verwendet, wartet auf dein Okay: Du siehst einen roten Hinweis über den Tabs und, im Agenten unter Status, die Installation unter Installationen warten auf Freigabe, mit dem Namen des Rechners, von dem aus sie sich verbindet.

Mit einem aktuellen Manifest passiert das kaum. Normal ist es bei einem älteren Agenten, der mit einem Manifest ohne BP_AGENT_INSTANCE_ID ausgerollt wurde, wenn du ihn auf eine andere Maschine umziehst, sein Volume löschst oder ihn von Grund auf neu installierst.

Drück auf Freigeben, wenn du den Rechner wiedererkennst. Sobald du einen freigibst, verliert der vorherige seinen Zugang.

---

Entfernen

1. In BolloPrint, in der Zeile des Agenten, Menü ⋮ → Löschen. Seine Drucker verschwinden mit ihm aus der Liste (ihr Verlauf geht nicht verloren: siehe Der lokale Agent).
2. Auf deinem Rechner stoppst und löschst du den Container: docker compose down in seinem Ordner, oder lösch den Stack in Portainer. BolloPrint kann das nicht für dich tun.
3. Wenn du ihn nicht mehr brauchst, lösch auch sein Volume:

docker volume rm bolloprint_agent_identity

---

Was du NICHT tun solltest

• Nutze dasselbe Manifest nicht auf zwei Rechnern gleichzeitig. Für zwei Rechner: zwei Agenten, jeder mit seinem eigenen.
• Erzeuge die Schlüssel nicht neu, um zu aktualisieren. Das trennt den Agenten, bis du ihn erneut ausrollst.
• Leg keinen neuen Agenten an, um zu aktualisieren. Aktualisieren ist derselbe Agent mit einer anderen Version; ein neuer hätte andere Schlüssel, und seine Drucker würden nicht von allein übernommen.
• Ändere die Schlüssel im Manifest nicht von Hand und kopier sie nicht in eine andere Installation.

---

Häufige Fragen

Muss ich Ports öffnen? Nein. Der Agent ruft BolloPrint an, nicht umgekehrt, und er veröffentlicht keinen Port auf deinem Rechner.

Verliere ich beim Aktualisieren oder Umziehen Drucker oder den Verlauf? Nein. Die Drucker und alles, was sie gedruckt haben, stehen in BolloPrint, nicht im Agenten.

Kann ich Versionen überspringen? Ja. Geh direkt zu der, die im Tab Bereitstellung angezeigt wird.

Wofür ist das Volume da? Darin speichert der Agent sein Protokoll der letzten Tage und die Versionen, die er beim Aktualisieren herunterlädt. Bei Agenten, die mit einem älteren Manifest ausgerollt wurden, auch seine Identität. Druckdaten speichert er dort nicht.

Läuft er auf einem Raspberry Pi? Ja. Das Image gibt es für Intel/AMD- und ARM-Rechner; Docker wählt von allein das passende.