💾 Agente su TrueNAS

Se hai un TrueNAS in laboratorio, hai già dove mettere l'agente locale: è acceso tutto il giorno e nella stessa rete delle tue stampanti. L'agente gira come un'app TrueNAS in più, accanto a quelle che hai già.

Questa pagina spiega come installarlo, collegarlo al tuo laboratorio, aggiornarlo, spostarlo e toglierlo. Cos'è l'agente e quali stampanti collega lo trovi in L'agente locale.

---

Prima di iniziare

Cosa ti serve	Come lo verifichi
TrueNAS 24.10 o successivo (Community Edition)	In TrueNAS, Dashboard → System Information → Version. Le versioni precedenti non hanno Install via YAML.
Le app di TrueNAS attivate	In Apps, in alto compare Apps Service Running. Se è la prima volta, TrueNAS ti chiede di scegliere il pool dove salvarle.
Entrare in TrueNAS con un utente amministratore	Solo un amministratore può installare app.
Essere proprietario del laboratorio in BolloPrint	Quando lo colleghi compaiono solo i laboratori di cui sei proprietario.
Che il TrueNAS e le stampanti siano nella stessa rete	Se sono in reti separate l'agente funziona lo stesso, ma dovrai aggiungere le stampanti tramite il loro IP.
Che il TrueNAS esca su internet	Nient'altro: non serve aprire porte né avere un IP fisso.

---

1. Copia lo YAML da BolloPrint

In BolloPrint, vai su Impostazioni → Stampanti → Agente locale → Nuovo agente e scegli TrueNAS.

Vedrai i passaggi e, sotto, un riquadro con lo YAML: il testo che dice a TrueNAS cosa installare. Premi Copia.

In quella schermata non c'è niente da creare: lo YAML è lo stesso per tutti i laboratori e non contiene chiavi. L'agente nasce quando lo colleghi, al passaggio 3.

Se ti interessa sapere cosa fa, lo YAML ha questa forma (copia sempre quello di BolloPrint, che ha la versione giusta nella riga 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 mette l'agente nella rete del tuo TrueNAS: così trova le stampanti.
• BP_LINK_LISTEN apre la sua pagina sulla porta 8257, e x-portals è ciò che aggiunge il pulsante Web UI in TrueNAS.
• data è la cartella dove l'agente salva la sua identità e il suo collegamento. Resiste a riavvii e aggiornamenti.

---

2. Installalo su TrueNAS

1. Entra in TrueNAS e apri Apps.
2. Premi Discover Apps.
3. In alto a destra, accanto a Custom App, apri il menu ⋮ e scegli Install via YAML.
4. In Name, scrivi bolloprint-agent.
5. In Custom Config, incolla lo YAML che hai copiato.
6. Premi Save.

TrueNAS scarica l'agente e lo avvia. In un minuto compare in Apps → Installed come Running.

---

3. Collegalo al tuo laboratorio

1. In Apps → Installed, premi bolloprint-agent. A destra, in Application Info, premi Web UI. La pagina dell'agente si apre in una nuova scheda.
2. La pagina dice «Questo agente non appartiene ancora a nessun laboratorio» e mostra un codice di otto caratteri, come 6E7B-9DEF. Premi Collega a BolloPrint.
3. Si apre BolloPrint. Se non hai effettuato l'accesso, accedi. Scegli il laboratorio a cui lo aggiungi.
4. BolloPrint ti mostra il Dispositivo (il nome del tuo TrueNAS e «TrueNAS») e il Codice. Controlla che sia lo stesso che compariva nella pagina dell'agente, dai un nome all'agente e premi Aggiungi al laboratorio.
5. Torni a BolloPrint, alla lista degli agenti. La pagina dell'agente ora dice Collegato a e il nome del tuo laboratorio.

Fatto. In Impostazioni → Stampanti → Agente locale vedrai l'agente con il logo di TrueNAS, Online.

---

4. Dagli le stampanti

L'agente comincia a cercare stampanti nella tua rete appena viene collegato. Quello che trova compare in Stampanti in rete locale, sotto la lista degli agenti, e da lì le registri. Quelle che non compaiono da sole, con Aggiungi per IP.

Come farlo con ogni marca lo trovi in Stampanti in rete locale.

---

Aggiornarlo

Non devi fare nulla. L'agente si aggiorna da solo: quando esce una versione nuova, la scarica, verifica che sia nostra e si riavvia con quella. La salva nella sua cartella dati, quindi resta su quella versione anche se riavvii l'app o il TrueNAS.

Per questo in TrueNAS l'app continua a dire Up to date e la riga image: del suo YAML non cambia: è la versione con cui è stato installato, non quella in esecuzione. Quella in esecuzione la vedi in BolloPrint, accanto all'agente.

Solo se BolloPrint ti avvisa che quell'agente ha bisogno di un aggiornamento manuale:

1. In Apps → Installed, premi bolloprint-agent e poi Edit.
2. In Custom Config, cambia solo la versione alla fine della riga image: con quella che mostra BolloPrint in Nuovo agente → TrueNAS. Non toccare nient'altro.
3. Premi Save.

L'agente resta collegato allo stesso laboratorio, con le stesse stampanti e il loro storico. Non c'è niente da ricollegare.

---

Spostarlo su un altro computer o reinstallarlo

Un agente installato da zero, su un altro computer o sullo stesso dopo averlo eliminato, è un agente nuovo:

1. Installalo e collegalo come nei passaggi da 1 a 3.
2. Aggiungi le tue stampanti al nuovo agente: passano a lui con il loro storico.
3. Elimina il vecchio agente in BolloPrint (Impostazioni → Stampanti → Agente locale, menu ⋮ dell'agente → Elimina).

---

Toglierlo

1. In BolloPrint, elimina l'agente: Impostazioni → Stampanti → Agente locale, menu ⋮ dell'agente → Elimina. In pochi secondi l'agente se ne accorge e la sua pagina torna a proporre Collega a BolloPrint.
2. In TrueNAS, Apps → Installed → bolloprint-agent → Delete.

Se lo elimini solo in TrueNAS, in BolloPrint continuerà a risultare Offline finché non lo elimini anche lì.

---

Se qualcosa non va

Cosa vedi	Cosa fare
Non trovi Install via YAML	Il tuo TrueNAS è precedente alla 24.10, oppure le app non sono attivate (in Apps, scegli il pool che ti chiede).
L'app non va oltre Deploying o resta in Stopped	Il TrueNAS non riesce a raggiungere internet per scaricare l'agente. Controlla la rete del TrueNAS e riavvia l'app da Apps → Installed.
Web UI apre una pagina che non si carica	Un'altra app usa già la porta 8257. In Edit, cambia ":8257" con ":8364" e il port: 8257 più in basso con port: 8364, tutti e due, e premi Save.
Il codice di BolloPrint non coincide con quello della pagina	Non confermare. Torna alla pagina dell'agente e premi di nuovo Collega a BolloPrint.
L'agente risulta Offline in BolloPrint	Controlla in TrueNAS che l'app sia Running e che il TrueNAS esca su internet. Il suo log è in Apps → Installed → bolloprint-agent → Workloads, nell'icona dei log.
È collegato ma non trova stampanti	Il TrueNAS e le stampanti devono essere nella stessa rete. Se non lo sono, aggiungile con Aggiungi per IP.