Indice del manuale

🐳 Agente su Docker

In 30 secondi

Per qualsiasi computer con Docker: un NAS, un mini-PC, un Raspberry Pi, un server. Anche con Portainer.
Lo crei in BolloPrint (Nuovo agente → Docker) e copi il suo manifesto, che contiene già il codice e l'identità dell'agente. Si mostra una sola volta.
Lo salvi così com'è come docker-compose.yml (o lo incolli in uno stack di Portainer) e lo avvii: in meno di un minuto risulta Online.
Si aggiorna da solo. Se un giorno ti chiediamo di farlo a mano, basta cambiare la versione dell'immagine e reinstallarlo, con le stesse chiavi.

Docker è il modo di installare l'agente su qualsiasi computer, che abbia o no un suo pacchetto. Se il tuo computer è un Synology, un QNAP, un TrueNAS, un PC con Windows o Home Assistant, guarda prima la sua pagina in L'agente locale: con il pacchetto hai meno passi.

Cosa ti serve

Un computer del laboratorio sempre acceso: un NAS, un mini-PC, il PC del laboratorio, un Raspberry Pi o un server che hai già.
Docker con Docker Compose, oppure Portainer, che è Docker con l'interfaccia.
Che stia nella stessa rete delle stampanti, così le trova da solo.

È leggero: non ha bisogno di un computer potente, e il manifesto gli mette un limite di 512 MB di memoria.

💡 Se l'agente non sta nella stessa rete delle stampanti

Non smette di funzionare. Quello che si perde è la scoperta automatica, perché l'annuncio di «sono qui» delle stampanti non passa da una rete all'altra (VLAN separate, rete ospiti, wifi a parte).

Le stampanti si aggiungono allora a mano, tramite il loro IP, e funzionano lo stesso, con tutte le loro prestazioni. L'unica cosa indispensabile è che le due reti possano parlarsi.

Su Docker Desktop (Windows e Mac) non c'è scoperta automatica. Lì Docker gira dentro una macchina virtuale che non vede la rete del computer, quindi le stampanti si aggiungono tramite IP. Funzionano esattamente uguale; c'è solo un passaggio in più al momento di registrarle. Su Windows, il programma di installazione per Windows non ha questa limitazione.

Crearlo in BolloPrint

Vai su Impostazioni → Stampanti e apri la scheda Agente locale.
Premi Nuovo agente. In Dove lo installerai?, scegli Docker, sotto Con un container.
Dagli un nome che riconosci. Meglio dov'è che cos'è: «Piano terra», «Capannone 2».
Premi Crea agente.
Compare il manifesto, con il codice dell'agente e la sua identità già scritti dentro. Lascia la scheda Docker Compose e premi Copia. Non c'è nulla da sostituire.
Con il manifesto salvato in un posto sicuro, premi Salva per chiudere la finestra.

🔐 Le chiavi si mostrano una volta sola

Copia il manifesto in quel momento. Le chiavi non scadono, ma non le conserviamo, quindi non possiamo mostrartele di nuovo. Se lo perdi, niente paura: apri l'agente con Modifica e, in Installazione, usa Rigenera le chiavi (più in basso, in questa pagina).

Ecco come si presenta il manifesto. Il tuo contiene le tue chiavi al posto di CHANGE_ME e la versione dell'agente giusta in quel momento al posto di 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

Non copiare questo: copia sempre il tuo dalla schermata di BolloPrint, che è quello con le tue chiavi.

Due righe che conviene capire:

BP_AGENT_CODE e BP_AGENT_INSTANCE_ID sono le chiavi dell'agente: chi è e in quale laboratorio lavora. Trattale come una password.
network_mode: host è ciò che permette all'agente di vedere la tua rete per trovare le stampanti. Non apre nessuna porta.

Avviarlo sul tuo computer

Il manifesto va così com'è, senza toccare nulla. Scegli il modo che usi.

Docker Compose

Crea una cartella per l'agente, per esempio bolloprint-agent.
Dentro, salva il manifesto come docker-compose.yml.
Da quella cartella, avvialo:

docker compose up -d

Portainer

Vai su Stacks → Add stack e dagli un nome, per esempio bolloprint-agent.
In Web editor, incolla il manifesto così com'è.
Premi Deploy the stack.

Il gestore di container del tuo NAS

Se il tuo NAS ha un suo gestore di container (il Container Manager di Synology, per esempio), crea un nuovo progetto, incolla il manifesto come suo docker-compose.yml e avvialo. È lo stesso di Docker Compose, con l'interfaccia.

Verificare che funzioni

In meno di un minuto, l'agente passa da Non installato a Online nella scheda Agente locale, con il nome del computer su cui gira e la sua versione. Non ti chiederà l'autorizzazione: quell'installazione è già autorizzata.

Se non compare, guarda il suo registro sul computer dove gira:

docker logs bolloprint_agent --tail 50

Cosa succede	Cosa guardare
Non compare mai	Il manifesto è stato incollato per intero, senza modifiche? Il computer arriva a internet? C'è un firewall che blocca l'uscita?
Compare, ma chiede l'autorizzazione	Il manifesto non contiene `BP_AGENT_INSTANCE_ID` (è stato modificato a mano o è di prima). Rigenera le chiavi e installa il nuovo manifesto così com'è.
È online ma non trova stampanti	Se sta su un'altra rete rispetto alle stampanti o usi Docker Desktop, è quello che ci si aspetta: aggiungile con Aggiungi per IP.

Con l'agente online, il passo successivo è collegare le tue stampanti: lo trovi in Stampanti in rete locale.

Aggiornarlo

Dalla versione 2026.1.1, l'agente si aggiorna da solo: quando esce una versione nuova, la scarica, verifica che sia nostra e si riavvia con essa. Non lo fa mai mentre una delle sue stampanti sta stampando. Non devi toccare il tuo file.

Serve farlo a mano solo se te lo chiede BolloPrint (per esempio, un agente installato tempo fa, con una versione precedente all'aggiornamento automatico). Lo vedrai così:

Sopra le schede di Impostazioni → Stampanti, un avviso con il nome del tuo agente: ««Piano terra» usa la versione XXXX. È disponibile la YYYY», con il pulsante Come aggiornare.
Nella scheda Agente locale, il numero di versione di quell'agente in arancione. In rosso, quella versione non è più supportata e conviene aggiornare quanto prima.

Cosa cambia

Cambia solo la riga image:, e al suo interno solo la versione, quello che viene dopo i due punti. Tutto il resto resta esattamente uguale: le chiavi, il volume e il resto della configurazione.

La versione giusta la trovi nella scheda Installazione del tuo agente (menu ⋮ → Modifica): è quella della riga image:.

Prima

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

Dopo

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

⚠️ Non incollare il manifesto della scheda Installazione sopra il tuo file

Per un agente già esistente, BolloPrint mostra CHANGE_ME al posto delle chiavi, perché non le conserva. Se incolli quel manifesto per intero sul tuo, cancelli le tue chiavi e l'agente smette di collegarsi. Cambia solo la versione della riga image: nel file che hai già.

Con Docker Compose

Apri il docker-compose.yml dell'agente e cambia la versione della riga image:.
Dalla cartella di quel file, scarica la versione nuova e riavvialo:

docker compose pull
docker compose up -d

Docker sostituisce il container con uno nuovo con la stessa configurazione e lo stesso volume.

Con Portainer

Vai su Stacks e apri lo stack dell'agente.
Premi Editor e cambia la versione della riga image:.
Attiva Re-pull image and redeploy (o Pull latest image, secondo la tua versione di Portainer) e premi Update the stack.

Verificare che sia andato bene

In meno di un minuto l'agente torna a comparire Online, con la versione nuova e senza colore di avviso. L'avviso sopra le schede scompare da solo. Mentre il container si riavvia, le stampanti possono comparire per qualche secondo come Disconnessa: tornano da sole, e le stampe in corso continuano sulla macchina.

E se la versione nuova ti dà problemi? Rimetti la versione precedente nella riga image: e reinstalla comunque. Poi apri una richiesta all'assistenza perché lo verifichiamo.

Spostarlo su un altro computer

L'identità dell'agente sta dentro il manifesto (BP_AGENT_INSTANCE_ID), quindi lo stesso file avviato su un'altra macchina è lo stesso agente: con le sue stampanti, senza chiedere l'autorizzazione e senza nulla da copiare a parte.

Sul computer vecchio, fermalo: docker compose down nella sua cartella, oppure elimina lo stack in Portainer.
Porta il docker-compose.yml sul computer nuovo e avvialo lì con docker compose up -d.

Ferma il vecchio prima di avviare il nuovo: due computer con le stesse chiavi nello stesso momento si rubano la connessione a vicenda.

Se il tuo manifesto è vecchio e non ha la riga BP_AGENT_INSTANCE_ID, avviandolo su un altro computer l'agente comparirà come installazione in attesa di autorizzazione (più in basso). Autorizzala e resta lo stesso agente, con tutto il suo storico.

Non hai più il file? Allora Rigenera le chiavi e installa il nuovo manifesto sul computer nuovo.

Rigenerare le chiavi

Nella finestra dell'agente (menu ⋮ → Modifica), scheda Installazione, Rigenera le chiavi crea un codice e un'identità nuovi e ti mostra il manifesto con quelli.

Usalo in due casi:

Hai perso il manifesto e devi installare di nuovo l'agente.
Pensi che qualcuno abbia le tue chiavi, per esempio perché compare un'installazione che non è tua.

Scollega l'agente all'istante: il codice e l'identità precedenti smettono di valere appena premi il pulsante, e l'agente resta scollegato finché non lo reinstalli con il nuovo manifesto. Qui sì che incolli il manifesto per intero, al posto di quello che avevi, e lo riavvii (docker compose up -d, oppure Update the stack in Portainer). Il volume resta com'è.

Se l'agente non si è mai collegato (risulta Non installato), rigenerare non scollega nulla.

Per aggiornare non serve rigenerare. Basta cambiare la versione dell'immagine.

Autorizzare le installazioni

L'installazione del manifesto che hai copiato entra direttamente. Qualsiasi altra installazione che usi quello stesso codice aspetta il tuo via libera: vedrai un avviso rosso sopra le schede e, dentro l'agente, in Stato, l'installazione in Installazioni in attesa di autorizzazione, con il nome del computer da cui si collega.

Con un manifesto attuale questo non succede quasi mai. È normale che succeda con un agente precedente, installato con un manifesto senza BP_AGENT_INSTANCE_ID, quando lo sposti su un'altra macchina, cancelli il suo volume o lo reinstalli da zero.

Premi Autorizza se riconosci il computer. Autorizzandone uno, il precedente perde l'accesso.

Se compare un'installazione in attesa che non hai messo tu, non autorizzarla: significa che qualcun altro ha il tuo codice. Rigenera le chiavi e reinstalla l'agente con il nuovo manifesto.

Toglierlo

In BolloPrint, nella riga dell'agente, menu ⋮ → Elimina. Le sue stampanti escono dall'elenco insieme a lui (il loro storico non si perde: vedi L'agente locale).
Sul tuo computer, ferma ed elimina il container: docker compose down nella sua cartella, oppure elimina lo stack in Portainer. BolloPrint non può farlo al posto tuo.
Se non lo userai più, elimina anche il suo volume:

docker volume rm bolloprint_agent_identity

Cosa NON bisogna fare

Non usare lo stesso manifesto su due computer contemporaneamente. Per due computer, due agenti, ciascuno con il suo.
Non rigenerare le chiavi per aggiornare. Scollega l'agente finché non lo reinstalli.
Non creare un agente nuovo per aggiornare. Aggiornare è lo stesso agente con un'altra versione; uno nuovo avrebbe altre chiavi e le sue stampanti non passerebbero da sole.
Non cambiare a mano le chiavi del manifesto e non copiarle in un'altra installazione.

Domande frequenti

Devo aprire porte? No. L'agente chiama BolloPrint, non il contrario, e non pubblica nessuna porta sul tuo computer.

Perdo stampanti o storico aggiornandolo o spostandolo? No. Le stampanti e tutto quello che hanno stampato sono in BolloPrint, non nell'agente.

Posso saltare delle versioni? Sì. Passa direttamente a quella che compare nella scheda Installazione.

A cosa serve il volume? A far sì che l'agente conservi il suo registro degli ultimi giorni e le versioni che scarica quando si aggiorna. Negli agenti installati con un manifesto vecchio, anche la sua identità. Non salva dati di stampa.

Funziona su un Raspberry Pi? Sì. L'immagine va bene per computer Intel/AMD e ARM; Docker sceglie da solo quella giusta.