🐳 Agent in Docker

Docker is de manier om de agent op elke computer te installeren, of die nu een eigen pakket heeft of niet. Is je computer een Synology, een QNAP, een TrueNAS, een pc met Windows of Home Assistant, kijk dan eerst naar zijn pagina in De lokale agent: met het pakket heb je minder stappen.

---

Wat je nodig hebt

• Een computer in de werkplaats die altijd aan staat: een NAS, een mini-pc, de pc van de werkplaats, een Raspberry Pi of een server die je al hebt.
• Docker met Docker Compose, of Portainer, dat is Docker met een scherm.
• Dat hij in hetzelfde netwerk als de printers zit, zodat hij ze vanzelf vindt.

Hij is licht: hij heeft geen krachtige computer nodig, en het manifest beperkt hem tot 512 MB geheugen.

In Docker Desktop (Windows en Mac) is er geen automatische detectie. Daar draait Docker in een virtuele machine die het netwerk van de computer niet ziet, dus de printers voeg je via IP toe. Ze werken precies hetzelfde; er is alleen één stap extra bij het toevoegen. Op Windows heeft het installatieprogramma voor Windows die beperking niet.

---

Hem aanmaken in BolloPrint

1. Ga naar Instellingen → Printers en open het tabblad Lokale agent.
2. Klik op Nieuwe agent. Kies bij Waar ga je hem installeren? voor Docker, onder Met een container.
3. Geef hem een naam die je herkent. Liever waar hij staat dan wat hij is: “Begane grond”, “Hal 2”.
4. Klik op Agent aanmaken.
5. Het manifest verschijnt, met de code van de agent en zijn identiteit er al in geschreven. Laat het tabblad Docker Compose staan en klik op Kopiëren. Je hoeft niets te vervangen.
6. Klik, als het manifest veilig bewaard is, op Opslaan om het venster te sluiten.

Zo ziet het manifest eruit. In het jouwe staan je sleutels in plaats van CHANGE_ME en de versie van de agent die op dat moment de juiste is in plaats van 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

Kopieer niet dit voorbeeld: kopieer altijd het jouwe van het scherm van BolloPrint, want daar staan jouw sleutels in.

Twee regels die je goed kunt begrijpen:

• BP_AGENT_CODE en BP_AGENT_INSTANCE_ID zijn de sleutels van de agent: wie hij is en in welke werkplaats hij werkt. Behandel ze als een wachtwoord.
• network_mode: host is wat de agent je netwerk laat zien, zodat hij de printers kan vinden. Er wordt geen enkele poort geopend.

---

Hem starten op je computer

Het manifest gaat er ongewijzigd in, zonder iets aan te passen. Kies de manier die jij gebruikt.

Docker Compose

1. Maak een map voor de agent, bijvoorbeeld bolloprint-agent.
2. Sla het manifest daarin op als docker-compose.yml.
3. Start hem vanuit die map:

docker compose up -d

Portainer

1. Ga naar Stacks → Add stack en geef hem een naam, bijvoorbeeld bolloprint-agent.
2. Plak in Web editor het manifest zoals het is.
3. Klik op Deploy the stack.

De containerbeheerder van je NAS

Heeft je NAS een eigen containerbeheerder (de Container Manager van Synology, bijvoorbeeld), maak dan een nieuw project aan, plak het manifest als zijn docker-compose.yml en start het. Het is hetzelfde als Docker Compose, maar met een scherm.

---

Controleren of het werkt

Binnen een minuut gaat de agent op het tabblad Lokale agent van Niet geïnstalleerd naar Online, met de naam van de computer waarop hij draait en zijn versie. Hij vraagt je niet om toestemming: deze installatie is al goedgekeurd.

Verschijnt hij niet, kijk dan in zijn log op de computer waar hij draait:

docker logs bolloprint_agent --tail 50

Wat er gebeurt	Waar je naar kijkt
Hij verschijnt nooit	Is het hele manifest geplakt, zonder wijzigingen? Kan de computer het internet bereiken? Blokkeert een firewall het uitgaande verkeer?
Hij verschijnt, maar vraagt om toestemming	In het manifest staat geen BP_AGENT_INSTANCE_ID (het is met de hand bewerkt of het is een oud manifest). Genereer de sleutels opnieuw en installeer het nieuwe manifest zoals het is.
Hij is online maar vindt geen printers	Zit hij in een ander netwerk dan de printers of gebruik je Docker Desktop, dan is dat normaal: voeg ze toe met Toevoegen via IP.

Staat de agent online, dan is de volgende stap je printers koppelen: dat lees je in Printers via het lokale netwerk.

---

Hem bijwerken

Vanaf versie 2026.1.1 werkt de agent zichzelf bij: komt er een nieuwe versie uit, dan downloadt hij die, controleert hij dat die van ons is en herstart hij ermee. Dat doet hij nooit terwijl een van zijn printers aan het printen is. Je hoeft je bestand niet aan te raken.

Met de hand hoeft het alleen als BolloPrint je erom vraagt (bijvoorbeeld bij een agent die al een tijd geleden is geïnstalleerd, met een versie van vóór de automatische update). Dat zie je zo:

• Boven de tabbladen van Instellingen → Printers een melding met de naam van je agent: “‘Begane grond’ draait versie XXXX. Versie YYYY is nu beschikbaar”, met de knop Hoe bijwerken.
• Op het tabblad Lokale agent het versienummer van die agent in het oranje. Staat het in het rood, dan wordt die versie niet meer ondersteund en kun je het beste zo snel mogelijk bijwerken.

Wat er verandert

Alleen de regel image: verandert, en daarin alleen de versie, wat na de dubbele punt staat. Al het andere blijft precies hetzelfde: de sleutels, het volume en de rest van de configuratie.

De juiste versie vind je op het tabblad Installatie van je agent (menu ⋮ → Bewerken): het is die in de regel image:.

Voor

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

Na

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

Met Docker Compose

1. Open het docker-compose.yml van de agent en pas de versie in de regel image: aan.
2. Download vanuit de map van dat bestand de nieuwe versie en start hem opnieuw:

docker compose pull
docker compose up -d

Docker vervangt de container door een nieuwe met dezelfde configuratie en hetzelfde volume.

Met Portainer

1. Ga naar Stacks en open de stack van de agent.
2. Klik op Editor en pas de versie in de regel image: aan.
3. Zet Re-pull image and redeploy aan (of Pull latest image, afhankelijk van je versie van Portainer) en klik op Update the stack.

Controleren of het goed is gegaan

Binnen een minuut staat de agent weer op Online, met de nieuwe versie en zonder waarschuwingskleur. De melding boven de tabbladen verdwijnt vanzelf. Terwijl de container herstart, kunnen de printers een paar seconden op Niet verbonden staan: ze komen vanzelf terug, en lopende prints gaan op de machine gewoon door.

En als de nieuwe versie problemen geeft? Zet de vorige versie terug in de regel image: en installeer op dezelfde manier. Open daarna een aanvraag bij support, zodat we ernaar kijken.

---

Hem naar een andere computer verhuizen

De identiteit van de agent staat in het manifest (BP_AGENT_INSTANCE_ID), dus hetzelfde bestand dat je op een andere machine start, is dezelfde agent: met zijn printers, zonder om toestemming te vragen en zonder dat je iets apart hoeft te kopiëren.

1. Stop hem op de oude computer: docker compose down in zijn map, of verwijder de stack in Portainer.
2. Neem het docker-compose.yml mee naar de nieuwe computer en start hem daar met docker compose up -d.

Stop de oude voordat je de nieuwe start: twee computers met dezelfde sleutels tegelijk zitten elkaars verbinding in de weg.

Is je manifest oud en staat de regel BP_AGENT_INSTANCE_ID er niet in, dan verschijnt de agent bij het starten op een andere computer als installatie die op autorisatie wacht (verderop). Autoriseer hem en hij blijft dezelfde agent, met zijn hele geschiedenis.

Heb je het bestand niet meer? Genereer de sleutels dan opnieuw en installeer het nieuwe manifest op de nieuwe computer.

---

De sleutels opnieuw genereren

In het venster van de agent (menu ⋮ → Bewerken), tabblad Installatie, maakt Sleutels opnieuw genereren een nieuwe code en identiteit aan en toont je het manifest daarmee.

Gebruik het in twee gevallen:

• Je bent het manifest kwijt en moet de agent opnieuw installeren.
• Je denkt dat iemand je sleutels heeft, bijvoorbeeld omdat er een installatie verschijnt die niet van jou is.

Het verbreekt de agent meteen: de vorige code en identiteit zijn niet meer geldig zodra je op de knop klikt, en de agent blijft offline tot je hem opnieuw installeert met het nieuwe manifest. Hier plak je het manifest wél helemaal, in plaats van het oude, en start je hem opnieuw (docker compose up -d, of Update the stack in Portainer). Het volume blijft zoals het is.

Heeft de agent nooit verbinding gemaakt (hij staat op Niet geïnstalleerd), dan verbreekt opnieuw genereren niets.

Om bij te werken hoef je niet opnieuw te genereren. Het is genoeg om de versie van de image te veranderen.

---

Installaties autoriseren

De installatie van het manifest dat je hebt gekopieerd komt direct binnen. Elke andere installatie die dezelfde code gebruikt, wacht op jouw akkoord: je ziet een rode melding boven de tabbladen en, in de agent, bij Status de installatie onder Installaties die op autorisatie wachten, met de naam van de computer waarvandaan hij verbinding maakt.

Met een actueel manifest gebeurt dit bijna nooit. Het is normaal dat het gebeurt met een oudere agent, geïnstalleerd met een manifest zonder BP_AGENT_INSTANCE_ID, als je hem naar een andere machine verhuist, zijn volume verwijdert of hem helemaal opnieuw installeert.

Klik op Autoriseren als je de computer herkent. Zodra je er een autoriseert, verliest de vorige zijn toegang.

---

Hem weghalen

1. Kies in BolloPrint, in de regel van de agent, menu ⋮ → Verwijderen. Zijn printers verdwijnen met hem uit de lijst (hun geschiedenis gaat niet verloren: zie De lokale agent).
2. Stop en verwijder de container op je computer: docker compose down in zijn map, of verwijder de stack in Portainer. BolloPrint kan dat niet voor je doen.
3. Ga je hem niet meer gebruiken, verwijder dan ook zijn volume:

docker volume rm bolloprint_agent_identity

---

Wat je NIET moet doen

• Gebruik hetzelfde manifest niet op twee computers tegelijk. Voor twee computers: twee agents, elk met zijn eigen manifest.
• Genereer de sleutels niet opnieuw om bij te werken. Dat verbreekt de agent tot je hem opnieuw installeert.
• Maak geen nieuwe agent aan om bij te werken. Bijwerken is dezelfde agent met een andere versie; een nieuwe zou andere sleutels hebben en zijn printers zouden niet vanzelf overgaan.
• Verander de sleutels in het manifest niet met de hand en kopieer ze niet naar een andere installatie.

---

Veelgestelde vragen

Moet ik poorten openzetten? Nee. De agent belt BolloPrint, niet andersom, en publiceert geen enkele poort op je computer.

Verlies ik printers of geschiedenis bij het bijwerken of verhuizen? Nee. De printers en alles wat ze hebben geprint staan in BolloPrint, niet in de agent.

Kan ik versies overslaan? Ja. Ga direct naar de versie die op het tabblad Installatie staat.

Waar dient het volume voor? Daarin bewaart de agent zijn log van de laatste dagen en de versies die hij downloadt om zichzelf bij te werken. Bij agents die met een oud manifest zijn geïnstalleerd, ook zijn identiteit. Er staan geen printgegevens in.

Werkt hij op een Raspberry Pi? Ja. De image werkt op Intel/AMD- en ARM-computers; Docker kiest zelf de juiste.