🐳 Agente en Docker

Docker es la forma de instalar el agente en cualquier equipo, tenga o no un paquete propio. Si tu equipo es un Synology, un QNAP, un TrueNAS, un PC con Windows o Home Assistant, mira antes su página en El agente local: con el paquete tienes menos pasos.

---

Qué necesitas

• Un equipo del taller siempre encendido: un NAS, un mini-PC, el PC del taller, una Raspberry Pi o un servidor que ya tengas.
• Docker con Docker Compose, o Portainer, que es Docker con pantalla.
• Que esté en la misma red que las impresoras, para que las encuentre solo.

Es ligero: no necesita un equipo potente, y el manifiesto le pone un tope de 512 MB de memoria.

En Docker Desktop (Windows y Mac) no hay descubrimiento automático. Ahí Docker corre dentro de una máquina virtual que no ve la red del equipo, así que las impresoras se añaden por IP. Funcionan exactamente igual; solo hay un paso más al darlas de alta. En Windows, el instalador de Windows no tiene esa limitación.

---

Crearlo en BolloPrint

1. Ve a Configuración → Impresoras y abre la pestaña Agente local.
2. Pulsa Nuevo agente. En ¿Dónde lo vas a instalar?, elige Docker, en Con un contenedor.
3. Ponle un nombre que reconozcas. Mejor dónde está que qué es: «Planta baja», «Nave 2».
4. Pulsa Crear agente.
5. Aparece el manifiesto, con el código del agente y su identidad ya escritos dentro. Deja la pestaña Docker Compose y pulsa Copiar. No hay nada que sustituir.
6. Con el manifiesto guardado en lugar seguro, pulsa Guardar para cerrar la ventana.

Este es el aspecto del manifiesto. El tuyo lleva tus claves en lugar de CHANGE_ME y la versión del agente que toca en ese momento en lugar 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

No copies este de aquí: copia siempre el tuyo desde la pantalla de BolloPrint, que es el que lleva tus claves.

Dos líneas que conviene entender:

• BP_AGENT_CODE y BP_AGENT_INSTANCE_ID son las claves del agente: quién es y en qué taller trabaja. Trátalas como una contraseña.
• network_mode: host es lo que deja al agente ver tu red para encontrar las impresoras. No abre ningún puerto.

---

Arrancarlo en tu equipo

El manifiesto va tal cual, sin tocar nada. Elige la forma que uses.

Docker Compose

1. Crea una carpeta para el agente, por ejemplo bolloprint-agent.
2. Dentro, guarda el manifiesto como docker-compose.yml.
3. Desde esa carpeta, arráncalo:

docker compose up -d

Portainer

1. Ve a Stacks → Add stack y ponle un nombre, por ejemplo bolloprint-agent.
2. En Web editor, pega el manifiesto tal cual.
3. Pulsa Deploy the stack.

El gestor de contenedores de tu NAS

Si tu NAS trae su propio gestor de contenedores (el Container Manager de Synology, por ejemplo), crea un proyecto nuevo, pega el manifiesto como su docker-compose.yml y arráncalo. Es lo mismo que Docker Compose, con pantalla.

---

Comprobar que funciona

En menos de un minuto, el agente pasa de Sin instalar a En línea en la pestaña Agente local, con el nombre del equipo en el que corre y su versión. No te pedirá autorización: esa instalación ya viene autorizada.

Si no aparece, mira su registro en el equipo donde corre:

docker logs bolloprint_agent --tail 50

Lo que pasa	Qué mirar
No aparece nunca	¿Se pegó el manifiesto entero, sin cambios? ¿El equipo llega a internet? ¿Hay un cortafuegos bloqueando la salida?
Aparece, pero pide autorización	El manifiesto no lleva BP_AGENT_INSTANCE_ID (se editó a mano o es de antes). Regenera las claves y despliega el manifiesto nuevo tal cual.
Está en línea pero no encuentra impresoras	Si está en otra red que las impresoras o usas Docker Desktop, es lo esperado: añádelas con Añadir por IP.

Con el agente en línea, el siguiente paso es conectar tus impresoras: lo tienes en Impresoras por red local.

---

Actualizarlo

Desde la versión 2026.1.1, el agente se actualiza solo: cuando sale una versión nueva, la descarga, comprueba que es nuestra y se reinicia con ella. Nunca lo hace mientras alguna de sus impresoras está imprimiendo. No tienes que tocar tu fichero.

Solo hace falta hacerlo a mano si BolloPrint te lo pide (por ejemplo, un agente instalado hace tiempo, con una versión anterior a la actualización automática). Lo verás así:

• Encima de las pestañas de Configuración → Impresoras, un aviso con el nombre de tu agente: ««Planta baja» usa la versión XXXX. Ya está disponible la YYYY», con el botón Cómo actualizar.
• En la pestaña Agente local, el número de versión de ese agente en naranja. En rojo, esa versión ya no está soportada y conviene actualizar cuanto antes.

Qué cambia

Solo cambia la línea image:, y dentro de ella solo la versión, lo que va después de los dos puntos. Todo lo demás se queda exactamente igual: las claves, el volumen y el resto de la configuración.

La versión que toca la tienes en la pestaña Despliegue de tu agente (menú ⋮ → Editar): es la de la línea image:.

Antes

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

Después

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

Con Docker Compose

1. Abre el docker-compose.yml del agente y cambia la versión de la línea image:.
2. Desde la carpeta de ese fichero, descarga la versión nueva y vuelve a arrancarlo:

docker compose pull
docker compose up -d

Docker sustituye el contenedor por uno nuevo con la misma configuración y el mismo volumen.

Con Portainer

1. Ve a Stacks y abre el stack del agente.
2. Pulsa Editor y cambia la versión de la línea image:.
3. Activa Re-pull image and redeploy (o Pull latest image, según tu versión de Portainer) y pulsa Update the stack.

Comprobar que ha ido bien

En menos de un minuto el agente vuelve a salir En línea, con la versión nueva y sin color de aviso. El aviso de encima de las pestañas desaparece solo. Mientras el contenedor se reinicia, las impresoras pueden salir unos segundos como Desconectada: vuelven solas, y las impresiones en marcha siguen su curso en la máquina.

¿Y si la versión nueva te da problemas? Vuelve a poner la versión anterior en la línea image: y despliega igual. Después abre un caso en soporte para que lo miremos.

---

Moverlo a otro equipo

La identidad del agente va dentro del manifiesto (BP_AGENT_INSTANCE_ID), así que el mismo fichero arrancado en otra máquina es el mismo agente: con sus impresoras, sin pedir autorización y sin nada que copiar aparte.

1. En el equipo antiguo, páralo: docker compose down en su carpeta, o borra el stack en Portainer.
2. Lleva el docker-compose.yml al equipo nuevo y arráncalo allí con docker compose up -d.

Para el antiguo antes de arrancar el nuevo: dos equipos con las mismas claves a la vez se pisan la conexión.

Si tu manifiesto es antiguo y no lleva la línea BP_AGENT_INSTANCE_ID, al arrancarlo en otro equipo el agente aparecerá como instalación pendiente de autorizar (más abajo). Autorízala y sigue siendo el mismo agente, con todo su historial.

¿Ya no tienes el fichero? Entonces Regenera las claves y despliega el manifiesto nuevo en el equipo nuevo.

---

Regenerar las claves

En la ventana del agente (menú ⋮ → Editar), pestaña Despliegue, Regenerar claves crea un código y una identidad nuevos y te enseña el manifiesto con ellos.

Úsalo en dos casos:

• Perdiste el manifiesto y necesitas volver a desplegar el agente.
• Crees que alguien tiene tus claves, por ejemplo porque aparece una instalación que no es tuya.

Corta el agente en el momento: el código y la identidad anteriores dejan de valer al pulsar el botón, y el agente queda desconectado hasta que lo vuelvas a desplegar con el manifiesto nuevo. Aquí sí pegas el manifiesto entero, en lugar del que tenías, y lo vuelves a arrancar (docker compose up -d, o Update the stack en Portainer). El volumen se queda como está.

Si el agente nunca llegó a conectarse (sale Sin instalar), regenerar no corta nada.

Para actualizar no hace falta regenerar. Basta con cambiar la versión de la imagen.

---

Autorizar instalaciones

La instalación del manifiesto que copiaste entra directa. Cualquier otra instalación que use ese mismo código espera tu visto bueno: verás un aviso rojo encima de las pestañas y, dentro del agente, en Estado, la instalación en Instalaciones pendientes de autorizar, con el nombre del equipo desde el que se conecta.

Con un manifiesto actual esto casi no pasa. Es normal que pase con un agente anterior, desplegado con un manifiesto sin BP_AGENT_INSTANCE_ID, cuando lo mueves a otra máquina, borras su volumen o lo reinstalas desde cero.

Pulsa Autorizar si reconoces el equipo. Al autorizar uno, el anterior deja de tener acceso.

---

Quitarlo

1. En BolloPrint, en la fila del agente, menú ⋮ → Eliminar. Sus impresoras salen de la lista con él (no se pierde su historial: ver El agente local).
2. En tu equipo, para y borra el contenedor: docker compose down en su carpeta, o borra el stack en Portainer. BolloPrint no puede hacerlo por ti.
3. Si no lo vas a volver a usar, borra también su volumen:

docker volume rm bolloprint_agent_identity

---

Lo que NO hay que hacer

• No uses el mismo manifiesto en dos equipos a la vez. Para dos equipos, dos agentes, cada uno con el suyo.
• No regeneres las claves para actualizar. Corta el agente hasta que lo despliegues otra vez.
• No crees un agente nuevo para actualizar. Actualizar es el mismo agente con otra versión; uno nuevo tendría otras claves y sus impresoras no pasarían solas.
• No cambies a mano las claves del manifiesto ni las copies a otra instalación.

---

Preguntas frecuentes

¿Tengo que abrir puertos? No. El agente llama a BolloPrint, no al revés, y no publica ningún puerto en tu equipo.

¿Pierdo impresoras o historial al actualizar o al moverlo? No. Las impresoras y todo lo que imprimieron están en BolloPrint, no en el agente.

¿Puedo saltarme versiones? Sí. Pasa directamente a la que aparece en la pestaña Despliegue.

¿Para qué sirve el volumen? Para que el agente guarde su registro de los últimos días y las versiones que descarga al actualizarse. En los agentes desplegados con un manifiesto antiguo, también su identidad. No guarda datos de impresión.

¿Funciona en una Raspberry Pi? Sí. La imagen sirve para equipos Intel/AMD y ARM; Docker elige sola la que toca.