💾 Agente no TrueNAS

Se tens um TrueNAS na oficina, já tens onde pôr o agente local: está ligado o dia todo e na mesma rede que as tuas impressoras. O agente corre como mais uma app do TrueNAS, ao lado das que já tenhas.

Esta página explica como o instalar, ligá-lo à tua oficina, atualizá-lo, mudá-lo de sítio e removê-lo. O que é o agente e a que impressoras se liga tens em O agente local.

---

Antes de começar

O que precisas	Como confirmas
TrueNAS 24.10 ou posterior (Community Edition)	No TrueNAS, Dashboard → System Information → Version. As versões anteriores não têm Install via YAML.
As apps do TrueNAS ativadas	Em Apps, aparece em cima Apps Service Running. Se for a primeira vez, o TrueNAS pede-te para escolheres o pool onde as guardar.
Entrar no TrueNAS com um utilizador administrador	Só um administrador pode instalar apps.
Ser proprietário da oficina no BolloPrint	Ao ligá-lo só aparecem as oficinas de que és proprietário.
Que o TrueNAS e as impressoras estejam na mesma rede	Se estiverem em redes separadas, o agente funciona na mesma, mas vais ter de acrescentar as impressoras pelo seu IP.
Que o TrueNAS tenha acesso à internet	Mais nada: não é preciso abrir portas nem ter IP fixo.

---

1. Copia o YAML do BolloPrint

No BolloPrint, vai a Configurações → Impressoras → Agente local → Novo agente e escolhe TrueNAS.

Vais ver os passos e, por baixo, uma caixa com o YAML: o texto que diz ao TrueNAS o que instalar. Prime Copiar.

Nesse ecrã não é preciso criar nada: o YAML é o mesmo para todas as oficinas e não leva chaves. O agente nasce quando o ligas, no passo 3.

Caso te interesse saber o que faz, o YAML tem esta forma (copia sempre o do BolloPrint, que leva a versão certa na linha image:):

services:
  bolloprint-agent:
    image: ghcr.io/bolloprint/bolloprint-agent:XXXX
    restart: unless-stopped
    network_mode: host
    mem_limit: 512m
    pids_limit: 512
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    environment:
      BP_PLATFORM: truenas
      BP_LINK_LISTEN: ":8257"
    volumes:
      - data:/var/lib/bolloprint

volumes:
  data:

x-portals:
  - name: Web UI
    scheme: http
    host: 0.0.0.0
    port: 8257
    path: /

• network_mode: host deixa o agente na rede do teu TrueNAS: assim encontra as impressoras.
• BP_LINK_LISTEN abre a sua página na porta 8257, e x-portals é o que põe o botão Web UI no TrueNAS.
• data é a pasta onde o agente guarda a sua identidade e a sua ligação. Sobrevive a reinícios e atualizações.

---

2. Instala-o no TrueNAS

1. Entra no TrueNAS e abre Apps.
2. Prime Discover Apps.
3. No canto superior direito, ao lado de Custom App, abre o menu ⋮ e escolhe Install via YAML.
4. Em Name, escreve bolloprint-agent.
5. Em Custom Config, cola o YAML que copiaste.
6. Prime Save.

O TrueNAS descarrega o agente e arranca-o. Num minuto aparece em Apps → Installed como Running.

---

3. Liga-o à tua oficina

1. Em Apps → Installed, prime bolloprint-agent. À direita, em Application Info, prime Web UI. A página do agente abre-se num separador novo.
2. A página diz «Este agente ainda não pertence a nenhuma oficina» e mostra um código de oito caracteres, como 6E7B-9DEF. Prime Ligar ao BolloPrint.
3. Abre-se o BolloPrint. Se não tiveres a sessão iniciada, inicia sessão. Escolhe a oficina à qual o vais adicionar.
4. O BolloPrint mostra-te o equipamento (o nome do teu TrueNAS e «TrueNAS») e o código. Confirma que é o mesmo que aparecia na página do agente, dá um nome ao agente e prime Adicionar à oficina.
5. Voltas ao BolloPrint, à lista de agentes. A página do agente diz agora Ligado a e o nome da tua oficina.

Já está. Em Configurações → Impressoras → Agente local vais ver o agente com o logótipo do TrueNAS, Online.

---

4. Dá-lhe as impressoras

O agente começa a procurar impressoras na tua rede assim que fica ligado. O que encontra aparece em Impressoras na rede local, por baixo da lista de agentes, e é daí que as registas. As que não aparecerem sozinhas, com Adicionar por IP.

Como o fazer com cada marca está em Impressoras por rede local.

---

Atualizá-lo

Não tens de fazer nada. O agente atualiza-se sozinho: quando sai uma versão nova, descarrega-a, confirma que é nossa e reinicia com ela. Guarda-a na sua pasta de dados, por isso continua nessa versão mesmo que reinicies a app ou o TrueNAS.

É por isso que no TrueNAS a app continua a dizer Up to date e a linha image: do seu YAML não muda: é a versão com que foi instalado, não a que está a correr. A que está a correr vês no BolloPrint, junto ao agente.

Só se o BolloPrint te avisar de que esse agente precisa de uma atualização manual:

1. Em Apps → Installed, prime bolloprint-agent e depois Edit.
2. Em Custom Config, muda só a versão no fim da linha image: para a que o BolloPrint mostra em Novo agente → TrueNAS. Não toques em mais nada.
3. Prime Save.

O agente continua ligado à mesma oficina, com as mesmas impressoras e o seu histórico. Não é preciso ligar nada outra vez.

---

Mudá-lo para outro equipamento ou reinstalá-lo

Um agente que se instala de raiz, noutro equipamento ou no mesmo depois de o apagar, é um agente novo:

1. Instala-o e liga-o como nos passos 1 a 3.
2. Adiciona as tuas impressoras ao agente novo: passam para ele com o seu histórico.
3. Elimina o agente antigo no BolloPrint (Configurações → Impressoras → Agente local, menu ⋮ do agente → Eliminar).

---

Removê-lo

1. No BolloPrint, elimina o agente: Configurações → Impressoras → Agente local, menu ⋮ do agente → Eliminar. Em poucos segundos o agente dá por isso e a sua página volta a oferecer Ligar ao BolloPrint.
2. No TrueNAS, Apps → Installed → bolloprint-agent → Delete.

Se só o apagares no TrueNAS, no BolloPrint vai continuar a aparecer como Desligado até o eliminares também aí.

---

Se alguma coisa não funcionar

O que vês	O que fazer
Não encontras Install via YAML	O teu TrueNAS é anterior à 24.10, ou as apps não estão ativadas (em Apps, escolhe o pool que te pede).
A app não passa de Deploying ou fica em Stopped	O TrueNAS não chega à internet para descarregar o agente. Verifica a rede do TrueNAS e volta a arrancar a app a partir de Apps → Installed.
Web UI abre uma página que não carrega	Outra app já usa a porta 8257. Em Edit, muda ":8257" para ":8364" e o port: 8257 mais abaixo para port: 8364, os dois, e prime Save.
O código do BolloPrint não coincide com o da página	Não confirmes. Volta à página do agente e prime outra vez Ligar ao BolloPrint.
O agente aparece como Desligado no BolloPrint	Confirma no TrueNAS que a app está Running e que o TrueNAS tem acesso à internet. O seu registo está em Apps → Installed → bolloprint-agent → Workloads, no ícone dos registos.
Está ligado mas não encontra impressoras	O TrueNAS e as impressoras têm de estar na mesma rede. Se não estiverem, acrescenta-as com Adicionar por IP.