Sommaire du manuel

🐳 Agent sur Docker

En 30 secondes

Pour n'importe quel poste avec Docker : un NAS, un mini-PC, un Raspberry Pi, un serveur. Aussi avec Portainer.
Vous le créez dans BolloPrint (Nouvel agent → Docker) et vous copiez son manifeste, qui contient déjà le code et l'identité de l'agent. Il n'est affiché qu'une seule fois.
Vous l'enregistrez tel quel sous le nom docker-compose.yml (ou vous le collez dans une stack Portainer) et vous le démarrez : en moins d'une minute, il apparaît En ligne.
Il se met à jour tout seul. Si un jour nous vous demandons de le faire à la main, il s'agit de changer la version de l'image et de redéployer, avec les mêmes clés.

Docker est la façon d'installer l'agent sur n'importe quel poste, qu'il ait ou non un paquet à lui. Si votre poste est un Synology, un QNAP, un TrueNAS, un PC sous Windows ou Home Assistant, regardez d'abord sa page dans L'agent local : avec le paquet, vous avez moins d'étapes.

Ce dont vous avez besoin

Un poste de l'atelier toujours allumé : un NAS, un mini-PC, le PC de l'atelier, un Raspberry Pi ou un serveur que vous avez déjà.
Docker avec Docker Compose, ou Portainer, qui est Docker avec une interface.
Qu'il soit sur le même réseau que les imprimantes, pour qu'il les trouve tout seul.

Il est léger : il n'a pas besoin d'une machine puissante, et le manifeste le limite à 512 Mo de mémoire.

💡 Si l'agent n'est pas sur le même réseau que les imprimantes

Il ne cesse pas de fonctionner. Ce que l'on perd, c'est la découverte automatique, parce que l'annonce « je suis là » des imprimantes ne traverse pas d'un réseau à l'autre (VLAN séparés, réseau invité, wifi à part).

Les imprimantes s'ajoutent alors à la main, par leur IP, et fonctionnent pareil, avec toutes leurs fonctionnalités. La seule chose indispensable est que les deux réseaux puissent se parler.

Sur Docker Desktop (Windows et Mac), il n'y a pas de découverte automatique. Là, Docker tourne dans une machine virtuelle qui ne voit pas le réseau du poste : les imprimantes s'ajoutent donc par IP. Elles fonctionnent exactement pareil ; il y a juste une étape de plus au moment de les enregistrer. Sous Windows, l'installateur Windows n'a pas cette limitation.

Le créer dans BolloPrint

Allez dans Paramètres → Imprimantes et ouvrez l'onglet Agent local.
Appuyez sur Nouvel agent. Dans Où allez-vous l'installer ?, choisissez Docker, sous Avec un conteneur.
Donnez-lui un nom que vous reconnaîtrez. Mieux vaut où il est que ce qu'il est : « Rez-de-chaussée », « Atelier 2 ».
Appuyez sur Créer l'agent.
Le manifeste apparaît, avec le code de l'agent et son identité déjà écrits dedans. Laissez l'onglet Docker Compose et appuyez sur Copier. Il n'y a rien à remplacer.
Une fois le manifeste mis en lieu sûr, appuyez sur Enregistrer pour fermer la fenêtre.

🔐 Les clés ne sont affichées qu'une seule fois

Copiez le manifeste à ce moment-là. Les clés n'expirent pas, mais nous ne les conservons pas, nous ne pouvons donc pas vous les montrer à nouveau. Si vous le perdez, pas de souci : ouvrez l'agent avec Modifier et, dans Déploiement, utilisez Régénérer les clés (plus bas sur cette page).

Voici à quoi ressemble le manifeste. Le vôtre contient vos clés à la place de CHANGE_ME et la version de l'agent qui convient à ce moment-là à la place de 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

Ne copiez pas celui-ci : copiez toujours le vôtre depuis l'écran de BolloPrint, c'est lui qui contient vos clés.

Deux lignes qu'il vaut mieux comprendre :

BP_AGENT_CODE et BP_AGENT_INSTANCE_ID sont les clés de l'agent : qui il est et dans quel atelier il travaille. Traitez-les comme un mot de passe.
network_mode: host est ce qui permet à l'agent de voir votre réseau pour trouver les imprimantes. Il n'ouvre aucun port.

Le démarrer sur votre poste

Le manifeste s'utilise tel quel, sans rien changer. Choisissez la méthode que vous utilisez.

Docker Compose

Créez un dossier pour l'agent, par exemple bolloprint-agent.
À l'intérieur, enregistrez le manifeste sous le nom docker-compose.yml.
Depuis ce dossier, démarrez-le :

docker compose up -d

Portainer

Allez dans Stacks → Add stack et donnez-lui un nom, par exemple bolloprint-agent.
Dans Web editor, collez le manifeste tel quel.
Appuyez sur Deploy the stack.

Le gestionnaire de conteneurs de votre NAS

Si votre NAS a son propre gestionnaire de conteneurs (le Container Manager de Synology, par exemple), créez un nouveau projet, collez le manifeste comme son docker-compose.yml et démarrez-le. C'est la même chose que Docker Compose, avec une interface.

Vérifier que ça fonctionne

En moins d'une minute, l'agent passe de Non installé à En ligne dans l'onglet Agent local, avec le nom du poste sur lequel il tourne et sa version. Il ne vous demandera pas d'autorisation : cette installation est déjà autorisée.

S'il n'apparaît pas, regardez son journal sur le poste où il tourne :

docker logs bolloprint_agent --tail 50

Ce qui se passe	Que regarder
Il n'apparaît jamais	Le manifeste a-t-il été collé en entier, sans modification ? Le poste atteint-il internet ? Un pare-feu bloque-t-il la sortie ?
Il apparaît, mais demande une autorisation	Le manifeste ne contient pas `BP_AGENT_INSTANCE_ID` (il a été modifié à la main ou il est ancien). Régénérez les clés et déployez le nouveau manifeste tel quel.
Il est en ligne mais ne trouve aucune imprimante	S'il est sur un réseau différent des imprimantes ou si vous utilisez Docker Desktop, c'est le comportement attendu : ajoutez-les avec Ajouter par IP.

Une fois l'agent en ligne, l'étape suivante consiste à connecter vos imprimantes : c'est dans Imprimantes en réseau local.

Le mettre à jour

Depuis la version 2026.1.1, l'agent se met à jour tout seul : quand une nouvelle version sort, il la télécharge, vérifie qu'elle vient bien de nous et redémarre avec elle. Il ne le fait jamais pendant qu'une de ses imprimantes est en train d'imprimer. Vous n'avez pas à toucher à votre fichier.

Il ne faut le faire à la main que si BolloPrint vous le demande (par exemple, un agent installé il y a longtemps, avec une version antérieure à la mise à jour automatique). Vous le verrez ainsi :

Au-dessus des onglets de Paramètres → Imprimantes, un avertissement avec le nom de votre agent : « « Rez-de-chaussée » utilise la version XXXX. La version YYYY est disponible », avec le bouton Comment mettre à jour.
Dans l'onglet Agent local, le numéro de version de cet agent en orange. En rouge, cette version n'est plus prise en charge et il vaut mieux mettre à jour au plus vite.

Ce qui change

Seule change la ligne image:, et à l'intérieur, seulement la version, ce qui vient après les deux-points. Tout le reste reste exactement pareil : les clés, le volume et le reste de la configuration.

La version qui convient se trouve dans l'onglet Déploiement de votre agent (menu ⋮ → Modifier) : c'est celle de la ligne image:.

Avant

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

Après

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

⚠️ Ne collez pas le manifeste de l'onglet Déploiement par-dessus votre fichier

Sur un agent qui existe déjà, BolloPrint affiche CHANGE_ME à la place des clés, car il ne les conserve pas. Si vous collez ce manifeste entier sur le vôtre, vous effacez vos clés et l'agent cesse de se connecter. Changez seulement la version de la ligne image: dans le fichier que vous avez déjà.

Avec Docker Compose

Ouvrez le docker-compose.yml de l'agent et changez la version de la ligne image:.
Depuis le dossier de ce fichier, téléchargez la nouvelle version et redémarrez-le :

docker compose pull
docker compose up -d

Docker remplace le conteneur par un nouveau, avec la même configuration et le même volume.

Avec Portainer

Allez dans Stacks et ouvrez la stack de l'agent.
Appuyez sur Editor et changez la version de la ligne image:.
Activez Re-pull image and redeploy (ou Pull latest image, selon votre version de Portainer) et appuyez sur Update the stack.

Vérifier que tout s'est bien passé

En moins d'une minute, l'agent réapparaît En ligne, avec la nouvelle version et sans couleur d'avertissement. L'avertissement au-dessus des onglets disparaît de lui-même. Pendant que le conteneur redémarre, les imprimantes peuvent apparaître quelques secondes comme Déconnectée : elles reviennent seules, et les impressions en cours poursuivent leur cours sur la machine.

Et si la nouvelle version vous pose des problèmes ? Remettez la version précédente dans la ligne image: et redéployez de la même façon. Puis ouvrez une demande au support pour que nous regardions.

Le déplacer sur un autre poste

L'identité de l'agent est dans le manifeste (BP_AGENT_INSTANCE_ID) : le même fichier démarré sur une autre machine est donc le même agent, avec ses imprimantes, sans demander d'autorisation et sans rien à copier à part.

Sur l'ancien poste, arrêtez-le : docker compose down dans son dossier, ou supprimez la stack dans Portainer.
Emportez le docker-compose.yml sur le nouveau poste et démarrez-le là-bas avec docker compose up -d.

Arrêtez l'ancien avant de démarrer le nouveau : deux postes avec les mêmes clés en même temps se disputent la connexion.

Si votre manifeste est ancien et ne contient pas la ligne BP_AGENT_INSTANCE_ID, en le démarrant sur un autre poste, l'agent apparaîtra comme installation en attente d'autorisation (plus bas). Autorisez-la et ce sera toujours le même agent, avec tout son historique.

Vous n'avez plus le fichier ? Alors régénérez les clés et déployez le nouveau manifeste sur le nouveau poste.

Régénérer les clés

Dans la fenêtre de l'agent (menu ⋮ → Modifier), onglet Déploiement, Régénérer les clés crée un nouveau code et une nouvelle identité et vous affiche le manifeste avec eux.

Utilisez-le dans deux cas :

Vous avez perdu le manifeste et vous devez redéployer l'agent.
Vous pensez que quelqu'un a vos clés, par exemple parce qu'une installation qui n'est pas la vôtre apparaît.

Cela coupe l'agent sur-le-champ : le code et l'identité précédents cessent d'être valables dès que vous appuyez sur le bouton, et l'agent reste déconnecté jusqu'à ce que vous le redéployiez avec le nouveau manifeste. Ici, oui, vous collez le manifeste entier, à la place de celui que vous aviez, et vous le redémarrez (docker compose up -d, ou Update the stack dans Portainer). Le volume reste tel quel.

Si l'agent ne s'est jamais connecté (il apparaît Non installé), régénérer ne coupe rien.

Pour mettre à jour, inutile de régénérer. Il suffit de changer la version de l'image.

Autoriser les installations

L'installation issue du manifeste que vous avez copié entre directement. Toute autre installation qui utilise ce même code attend votre feu vert : vous verrez un avertissement rouge au-dessus des onglets et, dans l'agent, sous État, l'installation dans Installations en attente d'autorisation, avec le nom du poste depuis lequel elle se connecte.

Avec un manifeste actuel, cela n'arrive presque jamais. C'est normal que cela arrive avec un agent plus ancien, déployé avec un manifeste sans BP_AGENT_INSTANCE_ID, quand vous le déplacez sur une autre machine, supprimez son volume ou le réinstallez de zéro.

Appuyez sur Autoriser si vous reconnaissez le poste. En en autorisant un, le précédent perd son accès.

Si une installation en attente que vous n'avez pas lancée vous-même apparaît, ne l'autorisez pas : cela signifie que quelqu'un d'autre a votre code. Régénérez les clés et redéployez l'agent avec le nouveau manifeste.

Le retirer

Dans BolloPrint, sur la ligne de l'agent, menu ⋮ → Supprimer. Ses imprimantes quittent la liste avec lui (leur historique n'est pas perdu : voir L'agent local).
Sur votre poste, arrêtez et supprimez le conteneur : docker compose down dans son dossier, ou supprimez la stack dans Portainer. BolloPrint ne peut pas le faire à votre place.
Si vous ne comptez plus l'utiliser, supprimez aussi son volume :

docker volume rm bolloprint_agent_identity

Ce qu'il ne faut PAS faire

N'utilisez pas le même manifeste sur deux postes à la fois. Pour deux postes, deux agents, chacun avec le sien.
Ne régénérez pas les clés pour mettre à jour. Cela coupe l'agent jusqu'à ce que vous le redéployiez.
Ne créez pas un nouvel agent pour mettre à jour. Mettre à jour, c'est le même agent avec une autre version ; un nouvel agent aurait d'autres clés et ses imprimantes ne passeraient pas seules.
Ne modifiez pas à la main les clés du manifeste et ne les copiez pas dans une autre installation.

Questions fréquentes

Dois-je ouvrir des ports ? Non. C'est l'agent qui appelle BolloPrint, et non l'inverse, et il ne publie aucun port sur votre poste.

Est-ce que je perds des imprimantes ou de l'historique en le mettant à jour ou en le déplaçant ? Non. Les imprimantes et tout ce qu'elles ont imprimé se trouvent dans BolloPrint, pas dans l'agent.

Puis-je sauter des versions ? Oui. Passez directement à celle qui apparaît dans l'onglet Déploiement.

À quoi sert le volume ? À ce que l'agent conserve son journal des derniers jours et les versions qu'il télécharge pour se mettre à jour. Sur les agents déployés avec un manifeste ancien, aussi son identité. Il ne conserve pas de données d'impression.

Fonctionne-t-il sur un Raspberry Pi ? Oui. L'image fonctionne sur les machines Intel/AMD et ARM ; Docker choisit tout seul celle qui convient.