🐳 Agente no Docker

O Docker é a forma de instalar o agente em qualquer equipamento, tenha ou não um pacote próprio. Se o teu equipamento é um Synology, um QNAP, um TrueNAS, um PC com Windows ou o Home Assistant, vê primeiro a sua página em O agente local: com o pacote tens menos passos.

---

O que precisas

• Um equipamento da oficina sempre ligado: um NAS, um mini-PC, o PC da oficina, um Raspberry Pi ou um servidor que já tenhas.
• Docker com Docker Compose, ou Portainer, que é Docker com ecrã.
• Que esteja na mesma rede que as impressoras, para as encontrar sozinho.

É leve: não precisa de um equipamento potente, e o manifesto limita-o a 512 MB de memória.

No Docker Desktop (Windows e Mac) não há deteção automática. Aí o Docker corre dentro de uma máquina virtual que não vê a rede do equipamento, por isso as impressoras acrescentam-se por IP. Funcionam exatamente igual; só há um passo a mais ao registá-las. No Windows, o instalador do Windows não tem essa limitação.

---

Criá-lo no BolloPrint

1. Vai a Configurações → Impressoras e abre o separador Agente local.
2. Prime Novo agente. Em Onde o vais instalar?, escolhe Docker, em Com um contentor.
3. Dá-lhe um nome que reconheças. Melhor onde está do que o que é: «Rés do chão», «Pavilhão 2».
4. Prime Criar agente.
5. Aparece o manifesto, com o código do agente e a sua identidade já escritos lá dentro. Deixa o separador Docker Compose e prime Copiar. Não há nada a substituir.
6. Com o manifesto guardado num sítio seguro, prime Guardar para fechar a janela.

Este é o aspeto do manifesto. O teu leva as tuas chaves em vez de CHANGE_ME e a versão do agente que é a certa nesse momento em vez 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

Não copies este daqui: copia sempre o teu a partir do ecrã do BolloPrint, que é o que leva as tuas chaves.

Duas linhas que convém perceber:

• BP_AGENT_CODE e BP_AGENT_INSTANCE_ID são as chaves do agente: quem é e em que oficina trabalha. Trata-as como uma palavra-passe.
• network_mode: host é o que deixa o agente ver a tua rede para encontrar as impressoras. Não abre nenhuma porta.

---

Arrancá-lo no teu equipamento

O manifesto vai tal como está, sem tocar em nada. Escolhe a forma que usas.

Docker Compose

1. Cria uma pasta para o agente, por exemplo bolloprint-agent.
2. Dentro, guarda o manifesto como docker-compose.yml.
3. A partir dessa pasta, arranca-o:

docker compose up -d

Portainer

1. Vai a Stacks → Add stack e dá-lhe um nome, por exemplo bolloprint-agent.
2. Em Web editor, cola o manifesto tal como está.
3. Prime Deploy the stack.

O gestor de contentores do teu NAS

Se o teu NAS traz o seu próprio gestor de contentores (o Container Manager do Synology, por exemplo), cria um projeto novo, cola o manifesto como o seu docker-compose.yml e arranca-o. É o mesmo que o Docker Compose, com ecrã.

---

Confirmar que funciona

Em menos de um minuto, o agente passa de Por instalar a Online no separador Agente local, com o nome do equipamento onde corre e a sua versão. Não te vai pedir autorização: essa instalação já vem autorizada.

Se não aparecer, vê o seu registo no equipamento onde corre:

docker logs bolloprint_agent --tail 50

O que se passa	O que ver
Nunca aparece	O manifesto foi colado por completo, sem alterações? O equipamento chega à internet? Há alguma firewall a bloquear a saída?
Aparece, mas pede autorização	O manifesto não leva BP_AGENT_INSTANCE_ID (foi editado à mão ou é antigo). Regenera as chaves e instala o manifesto novo tal como está.
Está online mas não encontra impressoras	Se estiver numa rede diferente da das impressoras ou usares o Docker Desktop, é o esperado: acrescenta-as com Adicionar por IP.

Com o agente online, o passo seguinte é ligar as tuas impressoras: tens isso em Impressoras por rede local.

---

Atualizá-lo

Desde a versão 2026.1.1, o agente atualiza-se sozinho: quando sai uma versão nova, descarrega-a, confirma que é nossa e reinicia-se com ela. Nunca o faz enquanto alguma das suas impressoras está a imprimir. Não tens de mexer no teu ficheiro.

Só é preciso fazê-lo à mão se o BolloPrint to pedir (por exemplo, um agente instalado há algum tempo, com uma versão anterior à atualização automática). Vais vê-lo assim:

• Por cima dos separadores de Configurações → Impressoras, um aviso com o nome do teu agente: ««Rés do chão» usa a versão XXXX. Já está disponível a YYYY», com o botão Como atualizar.
• No separador Agente local, o número de versão desse agente em laranja. Em vermelho, essa versão já não é suportada e convém atualizar quanto antes.

O que muda

Só muda a linha image:, e dentro dela só a versão, o que vem depois dos dois pontos. Tudo o resto fica exatamente igual: as chaves, o volume e o resto da configuração.

A versão certa tens no separador Instalação do teu agente (menu ⋮ → Editar): é a da linha image:.

Antes

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

Depois

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

Com Docker Compose

1. Abre o docker-compose.yml do agente e muda a versão da linha image:.
2. A partir da pasta desse ficheiro, descarrega a versão nova e volta a arrancá-lo:

docker compose pull
docker compose up -d

O Docker substitui o contentor por um novo com a mesma configuração e o mesmo volume.

Com Portainer

1. Vai a Stacks e abre o stack do agente.
2. Prime Editor e muda a versão da linha image:.
3. Ativa Re-pull image and redeploy (ou Pull latest image, dependendo da tua versão do Portainer) e prime Update the stack.

Confirmar que correu bem

Em menos de um minuto o agente volta a aparecer Online, com a versão nova e sem cor de aviso. O aviso por cima dos separadores desaparece sozinho. Enquanto o contentor reinicia, as impressoras podem aparecer uns segundos como Desligada: voltam sozinhas, e as impressões em curso continuam na máquina.

E se a versão nova te der problemas? Volta a pôr a versão anterior na linha image: e instala da mesma forma. Depois abre um pedido no suporte para vermos isso.

---

Mudá-lo para outro equipamento

A identidade do agente vai dentro do manifesto (BP_AGENT_INSTANCE_ID), por isso o mesmo ficheiro arrancado noutra máquina é o mesmo agente: com as suas impressoras, sem pedir autorização e sem nada para copiar à parte.

1. No equipamento antigo, para-o: docker compose down na sua pasta, ou apaga o stack no Portainer.
2. Leva o docker-compose.yml para o equipamento novo e arranca-o lá com docker compose up -d.

Para o antigo antes de arrancares o novo: dois equipamentos com as mesmas chaves ao mesmo tempo atropelam a ligação um do outro.

Se o teu manifesto é antigo e não leva a linha BP_AGENT_INSTANCE_ID, ao arrancá-lo noutro equipamento o agente vai aparecer como instalação a aguardar autorização (mais abaixo). Autoriza-a e continua a ser o mesmo agente, com todo o seu histórico.

Já não tens o ficheiro? Então regenera as chaves e instala o manifesto novo no equipamento novo.

---

Regenerar as chaves

Na janela do agente (menu ⋮ → Editar), separador Instalação, Regenerar chaves cria um código e uma identidade novos e mostra-te o manifesto com eles.

Usa-o em dois casos:

• Perdeste o manifesto e precisas de voltar a instalar o agente.
• Achas que alguém tem as tuas chaves, por exemplo porque aparece uma instalação que não é tua.

Desliga o agente no momento: o código e a identidade anteriores deixam de valer assim que premes o botão, e o agente fica desligado até o voltares a instalar com o manifesto novo. Aqui sim, colas o manifesto inteiro, em vez do que tinhas, e voltas a arrancá-lo (docker compose up -d, ou Update the stack no Portainer). O volume fica como está.

Se o agente nunca chegou a ligar-se (aparece Por instalar), regenerar não desliga nada.

Para atualizar não é preciso regenerar. Basta mudar a versão da imagem.

---

Autorizar instalações

A instalação do manifesto que copiaste entra logo. Qualquer outra instalação que use esse mesmo código espera pelo teu aval: vais ver um aviso vermelho por cima dos separadores e, dentro do agente, em Estado, a instalação em Instalações a aguardar autorização, com o nome do equipamento a partir do qual se liga.

Com um manifesto atual isto quase não acontece. É normal que aconteça com um agente anterior, instalado com um manifesto sem BP_AGENT_INSTANCE_ID, quando o mudas para outra máquina, apagas o seu volume ou o reinstalas de raiz.

Prime Autorizar se reconheces o equipamento. Ao autorizar um, o anterior deixa de ter acesso.

---

Removê-lo

1. No BolloPrint, na linha do agente, menu ⋮ → Eliminar. As suas impressoras saem da lista com ele (o seu histórico não se perde: vê O agente local).
2. No teu equipamento, para e apaga o contentor: docker compose down na sua pasta, ou apaga o stack no Portainer. O BolloPrint não o pode fazer por ti.
3. Se não o vais voltar a usar, apaga também o seu volume:

docker volume rm bolloprint_agent_identity

---

O que NÃO deves fazer

• Não uses o mesmo manifesto em dois equipamentos ao mesmo tempo. Para dois equipamentos, dois agentes, cada um com o seu.
• Não regeneres as chaves para atualizar. Desliga o agente até o voltares a instalar.
• Não cries um agente novo para atualizar. Atualizar é o mesmo agente com outra versão; um novo teria outras chaves e as suas impressoras não passariam sozinhas.
• Não mudes à mão as chaves do manifesto nem as copies para outra instalação.

---

Perguntas frequentes

Tenho de abrir portas? Não. É o agente que se liga ao BolloPrint, não o contrário, e não publica nenhuma porta no teu equipamento.

Perco impressoras ou histórico ao atualizar ou ao mudá-lo de equipamento? Não. As impressoras e tudo o que imprimiram estão no BolloPrint, não no agente.

Posso saltar versões? Sim. Passa diretamente para a que aparece no separador Instalação.

Para que serve o volume? Para o agente guardar o seu registo dos últimos dias e as versões que descarrega ao atualizar-se. Nos agentes instalados com um manifesto antigo, também a sua identidade. Não guarda dados de impressão.

Funciona num Raspberry Pi? Sim. A imagem serve para equipamentos Intel/AMD e ARM; o Docker escolhe sozinho a certa.