Installa l'Agente di Stampa

Cosa fa l'agente

L'Agente di Stampa collega le stampanti locali a Chemilla Labels. Sincronizza template e immagini, riceve job del tenant, genera le etichette in PDF e le invia alla coda di stampa del sistema operativo.

Installalo su un computer che rimane acceso e raggiunge tutte le stampanti che deve gestire.

• Gli installer sono disponibili dal workspace per Windows x64, macOS su Apple silicon e Linux x64.
• L'applicazione desktop espone stato, impostazioni, job locali, stampanti rilevate e log senza richiedere la riga di comando.
• Il nome del tenant locale conferma a quale workspace è associato l'agente.

Scarica e associa

1. 1

   Scarica l'agente stabile

   Usa l'elenco versioni qui sopra; per una nuova installazione scegli la versione indicata come Più recente.

2. 2

   Installalo e avvialo

   Usa il computer che raggiunge le stampanti interessate. Mantieni l'agente in esecuzione durante l'associazione.

3. 3

   Apri il link esatto di onboarding

   Quando l'agente mostra un link o un codice, apri quella richiesta mentre sei autenticato in Chemilla Labels.

4. 4

   Controlla la richiesta

   Seleziona il tenant e verifica hostname, piattaforma, versione e fingerprint prima di approvare.

5. 5

   Approva

   Assegna facoltativamente un nome al service account, poi approva. L'agente può registrare stampanti e ricevere job per il tenant.

Leggi lo stato dell'agente

Aggiorna la configurazione runtime

Scegli Config nella riga dell'agente per cambiare livello di log, frequenza heartbeat o sincronizzazione stampanti. Il salvataggio mette in coda una revisione desiderata; lo stato cambia quando l'agente la conferma.

Intervalli più frequenti migliorano l'aggiornamento ma generano più traffico. Mantieni i due minuti predefiniti salvo esigenze operative specifiche.

Usa l'applicazione Agent locale

Apri l'applicazione desktop sul computer dell'agente per la diagnostica locale. Stato mostra salute runtime e aggiornamenti; Impostazioni espone manutenzione e cartelle; Job offre anteprime e file generati; Stampanti mostra rilevamento e stato server; Log permette di copiare, aggiornare e aprire la cartella dei log.

• L'abilitazione delle stampanti per i job remoti si gestisce solo dal workspace web Labels. L'applicazione locale mostra quello stato, gestito dal server, in sola lettura.
• I file dei job locali possono essere controllati o mostrati su disco. L'eliminazione è limitata ai job completati e già sincronizzati.
• Usa Controlla aggiornamenti o l'avviso disponibile quando esiste una nuova versione stabile dell'agente.

Diagnosi in cinque minuti

Segui l'ordine seguente: ogni passaggio verifica un livello diverso e indica dove intervenire, senza reinstallare alla cieca.

1. 1

   Prova la stampante dal sistema operativo

   Verifica che sia online e stampa una pagina di prova direttamente da Windows, macOS o CUPS. Se questa prova fallisce, risolvi prima driver, coda, rete o supporto di stampa.

2. 2

   Apri l'Agent locale

   Controlla che Stato mostri il runtime attivo. Se l'applicazione non si apre o resta offline, passa alla procedura del tuo sistema operativo qui sotto.

3. 3

   Verifica il servizio locale

   Apri http://127.0.0.1:49210/health sul computer dell'Agent. La risposta deve identificare chemilla-label-agent, generation 2.

4. 4

   Verifica il percorso nel workspace

   L'Agent deve risultare online e Attivo, la configurazione Applicata e la stampante rilevata e abilitata. Attendi una sincronizzazione e aggiorna le pagine se hai appena modificato qualcosa.

5. 5

   Invia una sola copia

   Usa un template noto e un job di prova da una copia. Controlla prima lo stato in Job e nell'applicazione locale, poi l'uscita fisica.

Windows

• Scarica l'installer Windows x64 dall'elenco versioni ed eseguilo con l'utente che userà l'Agent. Se Windows SmartScreen interviene, prosegui solo dopo aver verificato che il file provenga dal sito ufficiale Labels.
• Se l'installazione è incompleta, chiudi davvero l'Agent dall'icona nell'area di notifica e avvia nuovamente lo stesso installer. Un riavvio di Windows elimina eventuali processi rimasti aperti.
• Apri Impostazioni > Bluetooth e dispositivi > Stampanti e scanner, seleziona la stampante e stampa una pagina di prova. L'Agent può usare soltanto code visibili e funzionanti per lo stesso utente Windows.
• Controlla che firewall, proxy o antivirus consentano HTTPS in uscita verso Labels e non blocchino l'applicazione. La porta 49210 è locale e deve essere libera.
• Se l'Agent si apre ma non compare nel workspace, completa o ripeti l'onboarding e approva la richiesta nel tenant corretto.

Invoke-RestMethod http://127.0.0.1:49210/health
Get-NetTCPConnection -LocalPort 49210 -ErrorAction SilentlyContinue

macOS

• Scarica il DMG per Apple silicon, aprilo e sposta Chemilla Labels Agent in Applicazioni. Avvia l'applicazione dalla cartella Applicazioni, non direttamente dal DMG.
• Se macOS blocca il primo avvio, verifica che il file provenga dal sito ufficiale Labels, poi usa Impostazioni di Sistema > Privacy e sicurezza per autorizzarlo.
• Chiudi l'Agent dal menu dell'icona nella barra dei menu prima di reinstallare o cambiare versione; chiudere soltanto la finestra lo lascia in esecuzione.
• Apri Impostazioni di Sistema > Stampanti e scanner e stampa una pagina di prova. Correggi prima eventuali problemi di driver, coda o rete.
• Se Stato resta offline, verifica il servizio locale e controlla i log dall'applicazione.

curl --fail --silent http://127.0.0.1:49210/health

Linux

Su Linux x64 puoi usare AppImage oppure il pacchetto DEB. L'AppImage supporta il controllo e l'installazione automatica degli aggiornamenti; le installazioni DEB si aggiornano installando manualmente il nuovo pacchetto.

• Per AppImage rendi eseguibile il file, avvialo e conservalo in un percorso stabile. Non spostarlo mentre l'Agent è in esecuzione.
• Per DEB installa il pacchetto con APT; in caso di errore leggi il messaggio del package manager prima di riprovare.
• Verifica con CUPS che la stampante sia presente, abilitata e impostata correttamente. Una stampa di prova CUPS deve riuscire prima del test da Labels.
• Se l'applicazione non parte, eseguila una volta dal terminale per leggere l'errore e verifica che la porta locale 49210 sia libera.
• Controlla che proxy e firewall consentano HTTPS in uscita verso Labels.

chmod +x Chemilla-Labels-Agent_*_linux-x64.AppImage
./Chemilla-Labels-Agent_*_linux-x64.AppImage

# In alternativa, pacchetto DEB
sudo apt install ./Chemilla-Labels-Agent_*_linux-x64.deb

curl --fail --silent http://127.0.0.1:49210/health
lpstat -p -d

Aggiornamento, reinstallazione e rollback

• Windows, macOS e Linux AppImage controllano gli aggiornamenti firmati automaticamente. Il pacchetto viene verificato prima dell'installazione e l'Agent viene riavviato al termine.
• Se un aggiornamento fallisce durante l'installazione, riapri l'Agent e controlla versione, stato e log prima di riprovare. Il runtime precedente viene conservato per il recupero automatico del backend.
• Per un rollback manuale, scarica la versione concordata dallo storico, chiudi completamente l'Agent e installala. Su Linux DEB installa esplicitamente il pacchetto scelto; con AppImage sostituisci il file soltanto dopo aver chiuso l'applicazione.
• Se la reinstallazione non basta, disinstalla soltanto l'applicazione, riavvia il computer e installa una versione nota. Windows usa App installate, macOS la cartella Applicazioni, Linux il package manager o la rimozione dell'AppImage.
• Non cancellare manualmente dati, configurazione, credenziali, log o cache durante un normale ripristino. Fallo soltanto con il supporto: potresti perdere l'associazione al tenant e le informazioni necessarie alla diagnosi.

Cosa raccogliere per il supporto

• Sistema operativo e versione, versione dell'Agent e formato usato per l'installazione.
• ID e nome dell'Agent, tenant selezionato, nome esatto della stampante e risultato della pagina di prova del sistema operativo.
• ID del job, stato e motivo mostrati dal workspace, con data, ora e fuso orario del tentativo.
• Risposta dell'endpoint locale /health e righe di log comprese tra poco prima e poco dopo l'errore.
• Non inviare password, client secret, token, chiavi API o l'intero database locale.