Documentazione · per l'amministratore

Guida per l'amministratore

Dal primo avvio alla gestione di tutti i giorni. Per ogni procedura è indicata la parte della console del motore in cui si trova e, quando serve, chi la può fare: un Proprietario o un Admin.

01 /Requisiti

• Windows 10 o Windows 11 a 64 bit, oppure Windows Server 2019 o 2022. Non c'è altro da installare: niente database, niente runtime.
• Un browser recente (Edge, Chrome o Firefox).
• La porta 8080 libera su questo computer (il motore), più una porta per ogni app (per esempio 8101, 8102…) e la stessa porta + 1000, usata dentro il computer.
• Una cartella in cui si può scrivere, per esempio C:\Pyrite: il motore tiene i suoi dati accanto a pyrite.exe. Evita C:\Program Files quando Pyrite parte dall'icona (per il servizio di Windows invece è il posto giusto: vedi Pyrite come servizio di Windows).

02 /Primo avvio

1. Copia la cartella dove vuoi tenerla, poi fai doppio clic su pyrite.exe.
2. Il motore parte in sottofondo, senza finestra nera: compare un'icona di Pyrite (i cubi del logo) nell'area di notifica, vicino all'orologio (se non la vedi, apri la freccetta ^ accanto all'orologio).
3. La prima volta che il programma parte da una cartella, Windows mostra la finestra «Sicurezza di Windows»: scegli Reti private e consenti. Se annulli, o scegli solo le reti pubbliche, gli altri computer della rete non raggiungono il portale e le app. Windows lo chiede di nuovo per ogni cartella nuova e per ogni file del programma con un altro nome o in un altro posto; una scelta sbagliata si corregge nelle impostazioni del firewall di Windows («Consenti app o funzionalità attraverso Windows Defender Firewall»), oppure con pyrite.exe firewall open da amministratore (vedi Il firewall di Windows).
4. Il browser si apre da solo; su un motore nuovo mostra la pagina di primo avvio (http://127.0.0.1:8080/setup/), dove crei il primo Proprietario del motore: il codice del primo avvio (vedi sotto), la tua email, il tuo nome (facoltativo) e una password con almeno 8 caratteri, una lettera maiuscola e una minuscola, un numero e un carattere speciale. Il Proprietario è una persona della rubrica, come tutte le altre.
5. Creato il Proprietario, si apre la console del motore, già con l'accesso fatto. Da lì in poi: console su http://NOME-O-IP-DEL-SERVER:8080/console/, portale su http://NOME-O-IP-DEL-SERVER:8080/ per chi usa le app. Finché il primo Proprietario non c'è, le app non partono.

Se il browser non si apre, apri a mano http://127.0.0.1:8080/setup/ su questo computer. Se la pagina non si può aprire proprio (per esempio su un server senza browser), crea il Proprietario da un prompt dei comandi nella cartella: pyrite.exe owner create EMAIL scrive una sola volta una password provvisoria; entra nella console con quella e scegline una nuova (vedi Per i tecnici).

Il codice del primo avvio

La pagina di primo avvio si apre da qualunque computer della rete, mai da internet, e solo finché un Proprietario non c'è. Per creare il Proprietario chiede un codice che Pyrite stampa sul server, così nessun altro della rete può prendersi il motore prima di te.

• Dove sta il codice: nella finestra del motore e in logs\engine.log (è qui che lo leggi quando Pyrite parte dall'icona). Con il doppio clic il browser si apre con il codice già scritto.
• Com'è fatto: 12 segni a gruppi di 4, per esempio ABCD-EFGH-JKMN, senza 0, O, 1, I e L. Maiuscolo o minuscolo, con o senza trattini.
• Codici sbagliati: dopo 5 codici sbagliati il motore ne stampa uno nuovo, e chi ha sbagliato aspetta un minuto (poi di più). Il codice cambia al massimo una volta al minuto, e un codice vuoto o scritto a metà non conta. Se il codice è cambiato mentre lo stavi usando, la pagina te lo dice e ti chiede quello nuovo. Se devi aspettare per troppi codici sbagliati e sei sul server (o arrivi da un tunnel SSH), la pagina ti dice come andare avanti subito: pyrite.exe owner create EMAIL dal server funziona anche con il motore acceso, oppure riavvia il motore.
• Solo con un nome del motore: la pagina si apre solo con un indirizzo del motore (il suo indirizzo IP o il nome del computer). Con un altro nome mostra una pagina che dice gli indirizzi giusti e dove sta il codice.
• Rete: nella stessa pagina si fanno le due domande sulla rete (o Salta), vedi Regole di rete. Quando il servizio di Windows c'è, la pagina chiede anche se Pyrite parte con la tua sessione (icona) o come servizio (vedi Pyrite come servizio di Windows).
• Su una VPS: da internet la pagina non esiste. Usa un tunnel SSH verso la porta del motore, oppure pyrite.exe owner create EMAIL.

03 /La console e i livelli

La console è l'area di gestione del motore: app, persone, gruppi, backup, eventi. Apri http://SERVER:8080/console/: la pagina d'accesso (/console/accesso/) chiede l'email e la password del tuo account della rubrica. Entrano solo Proprietari e Admin; il vecchio indirizzo /_/ porta alla console, quindi i segnalibri di prima funzionano ancora.

Se usi Pyrite da solo, il Proprietario sei tu: i livelli qui sotto servono solo quando altre persone ti aiutano a gestire.

Nella console e nel portale trovi ancora parole pensate per un'azienda: sono i testi del programma, e per ora restano così. «IT» è chi gestisce Pyrite; i «colleghi» sono le altre persone che usano le app; l'«ufficio» è la rete locale; «Tutta l'azienda» è l'unità di partenza, che puoi rinominare. Anche il titolo e i testi d'ingresso del portale («Applicazioni aziendali») li cambia un Proprietario, nella pagina Home del portale.

• Una sessione della console si chiude da sola dopo 30 minuti senza uso (il tempo si cambia nelle Regole di rete) e non dura mai più di 12 ore dall'accesso: vedi La console si chiude da sola. Dopo un riavvio del motore rifai l'accesso e torni alla stessa pagina.
• Se lavori nella console sul server, esci quando hai finito e blocca il desktop: una console lasciata aperta vale come la password di chi è entrato.
• Il menu con il tuo nome ha Profilo, Cambia password, l'Impaginazione della console (Predefinita del motore, Barra a sinistra, Menu in alto) ed Esci. L'impaginazione di chi non ha scelto la decide un Proprietario in Impostazioni del motore → Impaginazione della console.
• Nel menu in alto alcune voci hanno un nome breve: Portale (Home del portale), Lavori (Lavori pianificati), Storico (Storico del motore), Impostazioni (Impostazioni del motore) e Rete (Regole di rete). Sono le stesse pagine che la barra a sinistra mostra con il nome intero.
• Con il menu in alto, su uno schermo più stretto il tuo nome diventa un'icona (sotto i 1440 pixel), e sotto i 1280 pixel le voci del menu vanno su una seconda riga, che sul telefono scorre di lato.

I ruoli li dà un Proprietario nella scheda della persona, riquadro Unità e ruoli: Admin Persone o Admin App per unità, Admin App per una singola app, oppure Proprietario. I due ruoli di Admin si sommano sulla stessa persona. I ruoli dentro le app (per esempio responsabile o magazziniere) sono un'altra cosa: restano com'erano e si danno nella pagina dell'app, scheda Accessi e ruoli.

• Un ruolo si dà solo a chi fa parte dell'unità: prima si aggiunge la persona all'unità, poi le si dà il ruolo. Per toglierle l'unità si toglie prima il ruolo: il motore dice quale.
• Quando una persona perde l'ultimo ruolo (per esempio perché l'app che amministrava è stata eliminata o archiviata) torna Utente e deve rientrare. Se l'app torna dall'archivio il ruolo va ridato dalla scheda della persona.
• «Admin» dato come livello (per esempio dalla colonna livello dell'import) vale solo per chi fa parte di «Tutta l'azienda». Per le persone delle altre unità i ruoli si danno dalla scheda della persona.
• A chi si toglie un ruolo, o si cambia un'app o un'unità, viene chiesto di rientrare nella console; chi riceve qualcosa in più lo trova subito.
• Se arrivi dalla 0.7.5 con una sola unità, non cambia quasi niente. Chi era Admin resta «Admin (come nella 0.7.5)» con gli stessi limiti, e vede le stesse cose di prima. Puoi togliergli quel ruolo e dargli i nuovi: il pulsante Togli i limiti trasforma un Admin di prima in Admin Persone e, prima di farlo, mostra che cosa guadagna e che cosa perde.

Il portale saluta chi è entrato («Buongiorno, Anna.», con l'ora del suo computer e la prima parola del suo nome) e mostra le sue app come tessere, con una fascia del colore di ogni app; nel layout Elenco della home le app tengono il quadratino colorato. La home si sistema dalla console, in Home del portale.

04 /Più clienti su un motore: le unità

Un'unità è un gruppo chiuso di persone, gruppi e app: per esempio un cliente, un gruppo di lavoro o una sede. Con le unità un solo motore può servire più clienti, e ognuno vede solo le sue cose. All'inizio, e dopo l'aggiornamento dalla 0.7.5, c'è una sola unità, «Tutta l'azienda», e ci stanno tutti: se non ne crei altre, per chi usa Pyrite non cambia niente.

Chi vede che cosa

• Il Proprietario vede tutto, in tutte le unità.
• L'Admin Persone di un'unità vede e gestisce le persone e i gruppi di quell'unità, e il nome della sua unità in cima. Non vede le app. Ha la voce Storico con gli eventi sulle persone della sua unità.
• L'Admin App vede le sue app (avvio, backup, dati, accessi) e sceglie i gruppi dell'unità dell'app. Non vede le persone.
• L'Utente non entra nella console: usa il portale, e nel portale vede solo le applicazioni della sua unità. Prima di fare l'accesso il portale mostra solo le applicazioni ad accesso libero di «Tutta l'azienda».
• Un accesso vale solo dentro un'unità: un gruppo apre solo le app della sua unità, e una persona riceve un accesso diretto solo alle app di un'unità di cui fa parte. Il nome di un gruppo è unico dentro la sua unità (due clienti possono avere ognuno il suo «Vendite»).
• Una persona può stare in più unità. La cambia solo chi amministra tutte le sue unità; per gli altri la persona si vede ma non si cambia («persona protetta»).

Che cosa il motore non fa vedere a chi è di un altro cliente

Quello che è di un altro cliente «non esiste»: la risposta è la stessa che si riceve per un indirizzo sbagliato. A deciderlo è il motore, non la pagina: nessuna risposta porta dati che poi la pagina nasconde. Vale per:

• le app, nel portale e nella home;
• il nome di un'app: chi va all'indirizzo di un'app di un altro cliente legge «Applicazione» al posto del nome (chi è del cliente dell'app e non ha l'accesso legge il nome, con l'invito a chiedere l'accesso; chi non ha fatto l'accesso legge solo il nome delle app di «Tutta l'azienda»);
• le persone e i gruppi, lo storico e gli strumenti;
• chi gestisce un'app e scrive l'email di una persona per darle l'accesso: se la persona non è dell'unità dell'app la risposta è sempre «Nessuna persona di questa unità ha questa email», anche se esiste in un'altra unità;
• chi scrive l'id di un'unità che non amministra: la risposta è sempre «Il tuo livello non permette di farlo nella console», che l'unità esista o no.

Chi amministra senza essere Proprietario non legge mai nome ed email dei Proprietari: al loro posto c'è la parola «Proprietario». Resta uguale per tutti i clienti il titolo, il logo e le tessere in più della home.

Come si crea un'unità

Pagina Unità (solo il Proprietario; la voce è nella barra), Nuova unità, un nome. Il nome di un'unità è unico. Un'unità si elimina solo se è vuota. «Tutta l'azienda» si può rinominare ma non eliminare.

Come si sposta una persona o un'app

• Una persona. Nella sua scheda, riquadro Unità e ruoli, si accende l'unità nuova e poi si spegne la vecchia. Per togliere un'unità a una persona bisogna prima toglierla dai gruppi, dagli accessi e dai ruoli di quell'unità: se manca qualcosa il motore lo dice e non cambia niente.
• Un'app. Nella pagina Unità si sceglie l'app e l'unità di arrivo. La pagina mostra prima che cosa succede (anteprima) e si conferma. L'app porta con sé i gruppi che aprono solo lei; le persone che la usano ricevono in più la nuova unità. Se resterebbe un accesso a cavallo fra due unità, Pyrite si ferma e dice che cosa sistemare. Chi resta senza più niente nell'unità di partenza va tolto a mano dalla scheda della persona.
• Chi perde un'app o un gruppo per uno spostamento, o un ruolo perché l'unità è stata eliminata, deve rientrare nella console.
• Carica app. L'app nasce nell'unità di chi la carica. Il Proprietario la carica in «Tutta l'azienda» e poi, se serve, la sposta dalla pagina Unità. Chi può caricare in più di un'unità sceglie in cima alla pagina dove nasce l'app.
• Import delle persone. Lavora in un'unità: persone e gruppi nuovi nascono lì. Chi importa non può mettere sé stesso in un gruppo (la riga è segnata come errore, con il motivo).

Una persona ha sempre almeno un'unità, e un gruppo e un'app ne hanno sempre una: se un salvataggio (per esempio dalla scheda nativa) lascia il campo vuoto, torna «Tutta l'azienda».

05 /Doppia autenticazione

È un codice a sei cifre, preso da un'app sul telefono, che si scrive dopo email e password. La possono attivare le persone che entrano nella console (Proprietari e Admin). I codici dipendono dall'orologio: l'ora del server e quella del telefono devono essere giuste.

Come si attiva

1. Dal Profilo, dalla rete locale (non da internet), riquadro Doppia autenticazione, Attiva: scrivi la password.
2. Con un'app per i codici sul telefono inquadra il QR (o scrivi a mano la chiave).
3. Metti da parte i dieci codici di riserva (copia, scarica o stampa).
4. Scrivi il primo codice e spunta Li ho messi da parte.

Tutte le sessioni si chiudono: si rientra con password e codice. Il codice appena usato non vale più: si aspetta il prossimo, al più 30 secondi.

Come si entra

• Nella console: email e password, poi il codice a sei cifre del telefono oppure un codice di riserva. Ogni codice vale una volta sola.
• Nel portale: il codice serve anche lì. Dalla rete locale il portale chiede prima email e password e poi mostra il campo del codice. Da internet il campo del codice si vede subito a tutti, e chi non ha la doppia autenticazione lo lascia vuoto: è voluto, perché mostrarlo solo a chi la usa direbbe da fuori chi la usa. Aprire un'app dal portale non chiede un altro codice.
• Da internet il portale risponde sempre «Email, password o codice non corretti.», qualunque sia l'errore: è voluto.
• Codici sbagliati: cinque in 15 minuti fermano il codice di quella persona per 15 minuti, da qualunque computer, console e portale insieme. Nello storico compare un avviso (vuol dire che qualcuno conosce la sua password). Il conto si azzera al riavvio del motore.
• Ogni accesso con un codice di riserva lascia un avviso nello storico con quanti ne restano.

Se si perde il telefono

1. Se hai un codice di riserva: entra con quello e, dal Profilo, togli la doppia autenticazione (o rifai i codici). Per rifare i codici serve il codice del telefono: chi il telefono l'ha perso la toglie (lì un codice di riserva vale) e la riattiva.
2. Altrimenti un Proprietario apre la persona nella pagina Persone e preme Togli la doppia autenticazione. Da lì non la si toglie a sé stessi.
3. Se è un Proprietario a essere rimasto fuori e non ce n'è un altro, dal server: pyrite.exe owner two-factor-off EMAIL, a motore acceso o spento. Funziona solo per un Proprietario.

Chi può toglierla a chi

Un Admin che non è Proprietario non può toglierla a nessun altro.

La chiave e i backup

I codici sono protetti con una chiave che sta in control\doppia. Su Windows il file della chiave si apre solo su quel computer. Se il motore viene spostato su un altro computer, se Windows viene reinstallato o se il file della chiave si perde, chi aveva la doppia autenticazione risulta «da riattivare» e non entra più nella console finché non gli viene tolta: all'avvio lo storico dice chi è. Un Proprietario si libera con il comando dal server, poi la toglie agli altri dalla pagina Persone, e ognuno la attiva di nuovo. Per questo la cartella control\doppia va tenuta insieme al resto dei dati del motore in ogni copia che fai a mano.

Con update-restore

Il piano di update-restore (vedi Aggiornare dalla 0.7.5) dice chi perde la doppia autenticazione tornando indietro, a chi torna quella di allora e chi resta fuori perché la chiave del server è stata rifatta dopo il punto di ripristino.

06 /Persone e gruppi

dovePersone, Gruppi

Aggiungere una persona

«Nuova persona». Per un Proprietario apre la scheda di PocketBase: servono nome, email e una password iniziale, che deve rispettare le regole (almeno una maiuscola, una minuscola, un numero, un carattere speciale e la lunghezza minima delle Impostazioni del motore); poi, nella stessa scheda, sceglie il livello. Per un Admin apre una pagina del motore: nome, email e password iniziale, scritta da lui con le stesse regole oppure lasciata vuota e generata dal motore, che la mostra una volta sola; la persona ha il livello Utente. Con email e password la persona entra nel portale e al primo accesso sceglie una password sua: il cambio obbligatorio si accende da solo quando l'amministratore dà una password, e si può spegnere nella scheda («must_change_password»).

Cambiare nome, email e password

Si fa dalla scheda della persona: un Proprietario per tutti, un Admin per le persone di livello Utente. Una password data così è provvisoria: al primo accesso la persona dovrà sceglierne una nuova. Ognuno può cambiare la propria password dal portale, con «Cambia password». Se l'amministratore alza la lunghezza minima, chi ha una password più corta la cambia al prossimo accesso. Per chi dimentica la password vedi Password e recupero.

Disattivare una persona

Blocca subito l'ingresso nel portale, nella console e in tutte le app, anche per chi in quel momento sta lavorando. Quando qualcuno se ne va è il modo più rapido per chiudere tutti i suoi accessi in una volta. Un Admin può disattivare e riattivare le persone di livello Utente; eliminare una persona lo può fare solo un Proprietario.

Gruppi

Un gruppo raccoglie persone che hanno bisogno degli stessi accessi, per esempio un team. Dai l'accesso al gruppo una volta e vale per tutti i membri, anche per quelli che aggiungerai in seguito. Un Proprietario crea e cambia tutti i gruppi. Un Admin crea gruppi e ne cambia i membri solo se il gruppo dà accesso soltanto ad app gestite da lui; gli altri gruppi li vede in sola lettura, ma a qualsiasi gruppo può dare o togliere l'accesso alle sue app.

Importare persone, gruppi e accessi da Excel

Nella pagina Persone il pulsante «Importa da Excel» (Proprietari, e Admin che possono creare persone) apre «Importa persone e gruppi»: serve a caricare in una volta un team o un'azienda.

1. Scarica il modello (nella tua lingua): quattro fogli. Gruppi: Nome (obbligatorio) e Descrizione. Persone: Nome e cognome; Email (obbligatoria, una riga per persona); Livello (Utente o Admin; vuoto = Utente; Proprietario mai; Admin solo se importa un Proprietario); Gruppi (separati da punto e virgola, quelli che non esistono si creano); Attiva (sì o no; vuoto = sì; no = creata disattivata). Accessi: Gruppo, App (id, nome breve o nome) e Ruolo (facoltativo). Istruzioni.
2. Carica il file (Excel .xlsx o il vecchio .xls, fino a 10 MB; al massimo 5.000 persone e 1.000 gruppi). Un CSV vale come foglio Persone.
3. L'anteprima dice quante righe sono nuove, quante sono già presenti e gli errori, con il numero di riga. Un errore blocca tutto.
4. Conferma: tutto o niente, con una barra di avanzamento. È solo aggiunta: chi esiste già non cambia, nessuno esce da un gruppo o si disattiva.
5. Le password provvisorie (da cambiare al primo accesso) stanno in un file Excel che si scarica una volta sola, entro 10 minuti: non restano in nessun altro posto. Se si perde il file, la password si rifà dalla scheda della singola persona. Una persona nuova non riceve email: le password vanno comunicate a mano.

Un Admin può aggiungere solo persone di livello Utente, mettere persone in gruppi che può modificare e dare accessi solo alle app che gestisce. Il ruolo dentro un'app non è dell'accesso del gruppo ma della persona: la colonna Ruolo si controlla (l'app deve avere quel ruolo) e, a import finito, si dà alle persone nuove del gruppo se l'app è accesa; i ruoli che non si sono potuti dare (app spenta) sono elencati nell'esito, da dare dalla scheda «Accessi e ruoli» dell'app. L'esito finisce nello Storico del motore come un solo evento di riepilogo, senza password.

Le modifiche che un Admin fa a persone e gruppi finiscono nello Storico del motore, con il suo nome.

07 /Dare e togliere accessi

dovePersone o Gruppi, riquadro «Accesso alle app» nella scheda

Un accesso dice soltanto che una persona può entrare in un'app. Si dà direttamente a una persona oppure a un gruppo, e in quel caso vale per tutti i membri: nel riquadro «Accesso alle app» c'è un interruttore per ogni app. Una persona può avere l'accesso sia diretto sia tramite uno o più gruppi: le basta averne uno per entrare. Le app aperte a tutti non hanno accessi da gestire.

Un Proprietario dà e toglie l'accesso a tutte le app; un Admin solo alle app che gestisce, e mai a un Proprietario.

La scheda «Accessi e ruoli» della pagina dell'app mostra chi può entrare e come, ma non lo cambia: per cambiarlo si torna alla scheda della persona o del gruppo.

Togliere un accesso

Ha effetto subito, su tutte le app, anche per chi è già dentro: il motore controlla sessione e accesso a ogni richiesta.

08 /I ruoli dentro le app

dovepagina dell'app, scheda «Accessi e ruoli»

Il ruolo, per esempio «responsabile» o «magazziniere», è il livello di una persona dentro un'app e si gestisce lì. Non dipende dai gruppi, che decidono solo chi entra, né dal livello nella console.

• La prima volta che una persona entra dal portale, il motore crea dentro l'app un utente con la stessa email e lo stesso nome e gli dà il livello base dell'app (scheda Configurazione). Da lì il motore non tocca più il suo ruolo.
• Il ruolo si cambia nella scheda «Accessi e ruoli», con la tendina accanto alla persona; viene salvato nel database dell'app. Lo cambia un Proprietario o un Admin che gestisce l'app; i ruoli dei Proprietari solo un Proprietario. Per chi non è ancora entrato la scheda dice con quale ruolo entrerà.
• Se l'app lo prevede, anche chi ha il ruolo più alto può cambiare il ruolo delle altre persone dalle pagine dell'app. Nessuno può cambiare il proprio.
• Email, nome e password degli utenti dentro l'app vengono dalla rubrica e dall'app non si cambiano.

Sotto l'elenco, «Altri utenti dentro l'app» mostra gli utenti che esistono nel database dell'app ma non hanno l'accesso dal centro: la porta d'ingresso non li fa entrare.

09 /Persone già presenti nelle app

dovePersone, comando «Importa dalle app» (solo Proprietari)

Serve solo quando nelle app ci sono già utenti che non sono nella rubrica, per esempio app che avevano un loro login prima di passare al motore. Partendo da un motore vuoto e da app nuove non serve.

1. Apri Persone e scegli «Importa dalle app».
2. Il motore legge gli utenti che esistono dentro ogni app e porta nella rubrica quelli che mancano, con l'accesso diretto alle app in cui c'erano già. Il loro ruolo dentro le app resta com'era.
3. Sotto il riepilogo ci sono le password iniziali delle persone appena create. La console le mostra una volta sola: copiale subito e consegnale di persona o con un canale riservato.
4. Rileggi l'elenco e togli account di prova, doppioni e persone che non usano più le app.

10 /Che cosa può fare un'app

Gli script di un'app (le cartelle pb_hooks e pb_migrations) girano in un recinto: il motore impedisce loro di fare molte cose. Non servono scelte da parte tua: questo capitolo dice che cosa aspettarsi.

• File. Un'app non legge e non scrive file fuori dalla sua cartella, e scrive solo in state\. Non attraversa collegamenti o giunzioni. Un percorso che comincia con una barra è la radice del disco e viene rifiutato.
• Programmi. Un'app non lancia programmi e non fa ripartire sé stessa. Non mette le mani sul suo server e non ripristina copie di sicurezza.
• Database. Un'app non apre i database delle altre app. Le istruzioni SQL che portano fuori dal database (per esempio ATTACH) sono rifiutate.
• Controlli del motore. Un'app non può togliere né saltare i controlli del motore: la posta di un'app parte sempre e solo verso il server dichiarato, e ogni invio è nel registro.
• Rete. Un'app chiama solo gli indirizzi dichiarati in app.json. Da questa versione non può chiamare il motore (console, portale) né un'altra app dello stesso server, nemmeno dichiarandone l'indirizzo: riceve un rifiuto (403, codice app_origin) e nella console compare un evento «L'app X ha chiamato il motore» o «…l'app Y». Può chiamare sé stessa, ma la chiamata vale come se arrivasse da un PC della rete, non dal server. Può chiamare un altro programma di questo server dichiarato in app.json (per esempio un modello AI locale).
• Indirizzo di chi visita. Le app non ricevono più dai visitatori gli indirizzi scritti nelle intestazioni CF-Connecting-IP, X-Real-IP, True-Client-IP (e altre simili): le scrive il motore, con l'indirizzo vero.
• Chi risponde sulla porta dell'app. Le chiavi con cui il motore parla a un'app cambiano a ogni avvio dell'app. Il motore non manda niente alla porta interna di un'app (porta dell'app + 1000) se chi risponde non dimostra di essere il worker che ha avviato lui. Se risponde un altro programma, l'app risulta «failed» (non è partita) o «unhealthy» (era accesa), con il testo «Sulla porta interna N risponde un altro programma, non questa app»; nello storico c'è un evento di errore, in Panoramica un avviso rosso, e le persone vedono «L'applicazione non risponde in questo momento». Per rimediare: guarda chi usa la porta (netstat -ano | findstr :N, l'ultimo numero è il PID), chiudi quel programma e premi Riavvia. Anche senza Riavvia l'app riparte da sola entro pochi secondi da quando la porta è libera.

11 /L'icona vicino all'orologio

• Clic sinistro: sopra l'icona si apre una finestrella con lo stato e la versione del motore, da quanto è acceso, le app (accese, spente, in errore, con un pallino colorato), gli indirizzi del portale e della console con Copia, l'ultimo backup e i pulsanti Console, Portale, Log (la cartella dei log) ed Esci. Si chiude con un clic altrove, con un secondo clic sull'icona o con Esc; si usa anche con la tastiera (Tab, Invio) e segue il tema chiaro o scuro di Windows.
• Clic destro: il menu con Apri la console, Apri il portale, Apri la cartella dei log, una riga di stato (quante app sono accese), Avvia con Windows ed Esci.
• Doppio clic: apre la console. Anche un altro doppio clic su pyrite.exe mentre è acceso apre solo la console.

12 /Dove stanno le cose

Tutto resta nella cartella di pyrite.exe; il motore crea le cartelle al primo avvio.

Gli eventi si leggono nella console: i Proprietari li vedono tutti nello Storico del motore (barra laterale, vedi Lo storico del motore) e nei Log (in alto); gli Admin vedono gli eventi delle loro app nello Storico del motore, nella panoramica e nelle pagine delle app. La pagina di ogni app ha la scheda Log con le richieste arrivate all'app. Per una copia di tutto a mano, ferma il motore e copia l'intera cartella.

13 /Caricare e avviare un'app

Le app arrivano come file zip (per esempio da un agente di IA che segue lo standard per gli agenti).

1. Nella console apri Carica app nella barra laterale e scegli (o trascina) lo zip.
2. Il motore lo controlla a passi. Tre passi sono controlli veri (il pacchetto, la scheda app.json, la struttura delle cartelle); due, «Controllo di sicurezza» e «Compatibilità con lo standard», in questa alpha sono segnati demo: il loro punteggio è simulato. Controlla tu l'app prima di avviarla. Nel passo app.json il riepilogo elenca anche, per informazione, gli strumenti che l'app apre alle sue pagine e per chi, e gli indirizzi di rete che vuole raggiungere: leggili prima di installare. Un pacchetto con rotte sotto /api/tools/ si rifiuta: quel percorso è del motore. L'id di un'app non può essere un nome del motore (console, archivio…) né il nome di un dispositivo di Windows (con, nul, com1…). I file che si chiamano pyrite-archivio.json o pyrite-ripristino.json, accanto ad app.json, non si installano (il riepilogo lo dice): quei nomi il motore li tiene per l'Archivio.
3. Leggi il riepilogo e le note di consegna, poi premi Installa. L'app si installa spenta e non compare ancora nel portale.
   • Caricata da un Proprietario: si può avviare subito.
   • Caricata da un Admin: è in attesa di approvazione e la gestisce l'Admin. Finché un Proprietario non la approva, niente la avvia e non è nel portale. I Proprietari la trovano in App in attesa di approvazione nella panoramica e nella pagina dell'app (chi l'ha caricata e quando): la controllano e premono Approva. Per rifiutarla, un Proprietario preme Rifiuta (vedi App in attesa di approvazione).
4. Nella pagina dell'app premi Avvia. Poi dai l'accesso a persone o gruppi (Persone, Gruppi) e, se l'app ha ruoli, assegnali nella scheda Accessi e ruoli. Guarda anche le schede Strumenti per le pagine (che cosa possono usare le pagine, e chi; lì vedi anche i Lavori partiti dalle pagine, che puoi Annullare) e Rete in uscita (gli indirizzi che l'app raggiunge). In un'app pubblica che ha bisogno di utenti (per esempio chi può scrivere), creali nella scheda Dati (vedi Iscrizioni alle app).

Per provare c'è un'app di esempio, example-parts-pricelist.zip: è quella dello standard per gli agenti, con accesso e due ruoli, porta 8105.

Un Proprietario può installare un'app anche copiando la sua cartella in apps\ e premendo Rileggi cartelle.

Carica app e la porta

La porta scritta in app.json è una richiesta. Nel riepilogo di Carica app:

• Se le app ascoltano in rete e il firewall di Windows dice che la porta è chiusa, il riepilogo avvisa: dai PC l'app non si aprirà.
• Se la porta è già occupata, il pacchetto si ferma. In tutti e due i casi Carica app propone un'altra porta libera (una che il firewall lascia passare, quando lo sa dire) con un tasto Usa la porta N: un clic, e i controlli si rifanno con quella porta. La porta scelta viene scritta nell'app.json dell'app installata e lo Storico registra il cambio. Vale per le app nuove. Un aggiornamento non cambia mai la porta: l'app resta su quella che ha, e il riepilogo lo dice; la porta si cambia dalla scheda Configurazione. Un app.json con due chiavi uguali a meno delle maiuscole è rifiutato.
• Se il firewall è spento, o Pyrite non sa dirlo («non si sa»), non c'è nessun avviso.
• App già installate: se l'app ascolta in rete e la sua porta è chiusa dal firewall, la sua scheda e Panoramica mostrano un avviso, con il collegamento al riquadro del firewall e alla scheda Configurazione. La porta di un'app installata si cambia nella sua scheda Configurazione, campo Porta.

App in attesa di approvazione

• Quando un Admin carica un'app, i Proprietari ricevono un'email (serve la posta impostata nel motore; senza posta avvisa solo Panoramica). Il collegamento nell'email è sempre quello del motore; se l'indirizzo del motore è ancora quello di serie, l'email parte senza collegamento.
• Nella scheda dell'app, chi l'ha caricata vede quando i Proprietari sono stati avvisati (o che la posta non c'è) e può premere Ricorda ai Proprietari: una volta ogni 24 ore, e solo con la posta impostata.
• Un Proprietario può premere Rifiuta e scrivere il motivo (da 1 a 300 caratteri). L'app viene archiviata e lo Storico registra il motivo. Chi l'aveva caricata legge il motivo in Panoramica per 14 giorni e in un'email, se la posta è impostata; tutte e due dicono «un Proprietario», non quale (il nome resta solo nello Storico). L'Admin che l'aveva caricata perde il ruolo su quell'app: per vedere l'avviso in Panoramica deve rientrare nella console.
• Se un rifiuto è rimasto a metà (la cartella dell'app non si è potuta togliere, quindi l'archiviazione non è finita), Approva non va avanti: la pagina dice di finire o eliminare prima quell'archiviazione dalla pagina Archivio.
• Un'app non approvata continua a non potersi avviare e non è nel portale.

Aggiornare un'app installata

Una versione nuova di un'app arriva come uno zip con lo stesso identificativo. Parti da Carica app, oppure da Aggiorna da zip nella scheda Configurazione dell'app (da lì lo zip di un'altra app si rifiuta).

1. Il motore fa i controlli di sempre e poi mostra che cosa cambia rispetto alla versione installata: versioni, campi di app.json, migrazioni nuove. Non si tocca ancora niente. Una migrazione rinominata o tolta, e un app.json nuovo che allarga i permessi (accesso che diventa pubblico, indirizzi nuovi in network, toolAccess o tools nuovi, ruoli nuovi), sono un avviso forte: leggilo, e vai avanti solo se sei sicuro. Un Proprietario approva proprio il pacchetto che vede nel riepilogo: se intanto un Admin ne carica un altro, la pagina mostra il riepilogo nuovo. Un pacchetto con una cartella state si rifiuta: i dati non si sostituiscono mai.
2. Un Proprietario preme Aggiorna adesso. Un Admin che gestisce l'app lo manda per l'approvazione: la versione in uso continua a girare finché un Proprietario non lo approva o lo rifiuta nella stessa pagina.
3. Tutto o niente: l'app si ferma (i lavori pianificati in corso si interrompono, come con un riavvio), si fa una copia di sicurezza di release, app.json e dei dati dell'app (tutta la cartella state, senza i temporanei) in control\aggiornamenti_app\<app>, dove gli script dell'app non arrivano, si sostituiscono i file, la versione nuova parte, applica le migrazioni e deve rispondere. Un'app che era ferma parte solo per questo, poi torna ferma.
4. Se qualcosa non va, tutto torna da solo com'era, dati compresi (controllato con le impronte), la versione di prima riparte e la pagina dice perché. Se il motore o il PC si spengono a metà, al prossimo avvio il motore rimette la versione di prima, prima di avviare le app, e lo scrive negli eventi.

Dopo, un Proprietario può premere Torna alla versione di prima nella stessa scheda, scrivendo l'identificativo dell'app. I dati scritti dopo l'aggiornamento per l'app si perdono: prima lo stato di quel momento si copia da parte in una cartella da_parte_…, che chi gestisce Pyrite può leggere a mano. Per ogni app il motore tiene la copia dell'ultimo aggiornamento riuscito e l'ultima copia messa da parte (al più due cartelle, ognuna grande come i dati dell'app). Anche la porta torna quella che aveva prima dell'aggiornamento: se nel frattempo l'hai cambiata dalla scheda Configurazione, dopo il ritorno va cambiata di nuovo da lì; il riepilogo che compare prima del ritorno lo dice. Contengono dati personali: per cancellare davvero i dati di una persona vanno cancellati anche lì, a mano.

Archiviare l'app. Le copie di sicurezza non entrano nella voce dell'archivio: vanno in control\aggiornamenti_app\_archiviate\<voce>, la pagina Archivio le mostra con la voce, e si eliminano quando elimini la voce. Dopo un ripristino dall'archivio Torna alla versione di prima non c'è più. Le copie di un'app la cui cartella non c'è più vanno da parte all'avvio del motore e finiscono negli eventi a ogni avvio, finché non le togli.

App ferma dopo un aggiornamento. Se la versione di prima non si è potuta rimettere (disco pieno, un file tenuto da un altro programma, una copia rovinata), l'app resta ferma con il segno control\aggiornamenti_app\<app>\in_corso.json e il motore riprova a ogni avvio. Togli la causa e riavvia il motore. Se non basta: a motore fermo, copia a mano release, app.json e state da file\apps\<app> della copia che il segno nomina, poi cancella in_corso.json. Senza il segno il motore non cancella più quella copia: lo scrive negli eventi a ogni avvio, e la togli tu quando l'app funziona. update-restore non parte finché c'è un segno: prima avvia il motore una volta.

14 /Modificare un'app

dovepagina dell'app, scheda Configurazione (solo Proprietari)

Si possono cambiare nome, responsabile, descrizione, accesso, versione, porta, limite di memoria, ruoli e livello base. La versione precedente della scheda resta salvata accanto come app.json.prima. Se cambiano porta, memoria, accesso o ruoli, l'app si riavvia da sola in pochi secondi; nel frattempo la sua porta risponde «si sta aggiornando». Lo stesso succede se modifichi app.json a mano e poi premi «Rileggi cartelle».

I ruoli funzionano solo se l'app ha un campo per il ruolo dei suoi utenti (auth.roleField nella scheda): se manca, la Configurazione lo segnala sotto il campo dei ruoli.

Nella stessa scheda ci sono i controlli consigliati dalla guida di PocketBase per la messa in produzione. Il limite di richieste si attiva con un clic.

Per aggiornare un'app da uno zip vedi Aggiornare un'app installata.

Aggiornare il codice di un'app a mano

1. Fai un backup manuale dell'app.
2. Sostituisci i file dentro apps\<id>\release. Non toccare state, dove stanno i dati.
3. Riavvia l'app dalla sua pagina: le migrazioni nuove si applicano all'avvio. Poi controlla Stato e Log.

15 /Strumenti del motore

doveStrumenti; pagina dell'app, scheda Configurazione, riquadro «Strumenti del motore» (solo Proprietari)

Il motore offre alle app degli strumenti pronti per i lavori pesanti, che gli script dell'app usano senza programmi o librerie da aggiungere. Sono pronti otto strumenti: import ed export Excel e CSV, PDF, foto, numerazioni, storico delle modifiche, statistiche e lavori pianificati; restano «in programma» le email e le notifiche e le prenotazioni.

• Uno strumento si attiva per una sola app, con l'interruttore nella Configurazione dell'app o con l'elenco tools della sua scheda. Vale subito, senza riavviare l'app.
• Accendi solo gli strumenti che l'app usa davvero: le note di consegna dell'app li elencano. Se uno script usa uno strumento spento riceve un errore che spiega come attivarlo.
• La pagina «Strumenti» dice cosa fa ogni strumento e quali app lo usano, e segnala le schede che chiedono uno strumento che non esiste.

Per usare l'import dalla console non serve attivare niente: la scheda «Importa» c'è in ogni app con database.

16 /Importare dati da Excel o CSV

dovepagina dell'app, scheda «Importa» (Proprietari e Admin dell'app)

1. Carica il file (Excel .xlsx o il vecchio .xls di Excel 97-2003, CSV oppure JSON — .json, .jsonl, .ndjson — fino a 100 MB; i file JSON al più 128 MB). I file con la password, quelli di Excel 95 e precedenti, quelli rovinati e i documenti di Word o PowerPoint con il nome .xls si rifiutano subito con un messaggio: riaprili con Excel e salvali come .xlsx. Un file Excel può avere al massimo 5.000.000 di testi diversi e 256 MB di testo: oltre, il motore risponde «troppo testo». Capita solo con file enormi; in quel caso dividi il file o salvalo come CSV.
2. Scegli il formato. CSV: il separatore (di partenza il punto e virgola). Excel: il foglio e il modo, cioè solo dati (i dati partono dalla prima riga e le colonne si chiamano A, B, C…), con titoli (la prima riga dà i nomi delle colonne) oppure con intestazione: nell'anteprima scegli le righe da scartare in testa, la riga dopo dà i nomi e i dati partono da quella successiva.
3. Controlla l'anteprima: colonne, tipi riconosciuti, prime righe, avvisi.
4. Scegli la raccolta e controlla gli abbinamenti tra colonne e campi proposti dal motore. Con una chiave (per esempio la targa) un nuovo import aggiorna i record già presenti invece di duplicarli.
5. Fai la prova: controlla tutto e non salva niente. Le righe con errori sono elencate con il numero di riga e il motivo.
6. Importa. L'avanzamento resta a vista; alla fine c'è l'esito. Le impostazioni si possono salvare come ricetta da riusare con il file del mese dopo.

Ogni importazione resta nello storico della scheda, con chi l'ha fatta, e si può annullare: i record creati si tolgono e quelli aggiornati tornano come prima. Importazioni e annullamenti finiscono anche nello Storico del motore.

Importare tutto il file

Nel passo «Destinazione» si sceglie «Una raccolta» oppure «Tutto il file», che è la scelta di partenza anche con un foglio solo. Con «Tutto il file» il motore guarda ogni foglio (o elenco, nel JSON) e propone:

• la raccolta dell'app che gli somiglia di più, con la somiglianza («simile al 97%»; il distintivo è verde solo dal 75% in su e senza dubbi, altrimenti «da controllare»); un foglio con un nome che non dice niente («Foglio1») non sceglie da solo;
• le colonne → campi (dettagli apribili) e la chiave;
• l'ordine di caricamento, secondo i collegamenti tra le raccolte (i fornitori prima degli ordini), e le raccolte collegate riempite dallo stesso foglio («Da questo foglio anche in «fornitori»», si può togliere); un foglio con tutto dentro si divide nelle sue raccolte;
• «Cosa non trova posto»: quello che non ha saputo mettere (fogli nascosti, raccolte non ammesse, colonne senza campo), con il testo da girare a chi costruisce l'app.

La chiave che riconosce le righe già presenti il motore la sceglie da solo solo quando è sicura: un indice unico dell'app, oppure, in una raccolta senza collegamenti nel file (singoli o a più valori), un codice, una targa o un nome con valori tutti diversi e pieni. Per una raccolta collegata a un'altra (le righe di un ordine, gli articoli di una categoria) non la sceglie mai, così un import non aggiorna mai la riga di un altro ordine: un avviso suggerisce quella da scegliere a mano, per esempio «ordine + articolo», e con quella, reimportando lo stesso file, i record si riconoscono e si aggiornano (salvala nella ricetta). Una chiave che trova più record già presenti scarta la riga e dice perché, e così un collegamento che trova più record (due ordini «O-1»).

L'«Anteprima (non salva niente)» mostra, per ogni raccolta, cosa verrebbe creato, aggiornato, già uguale o scartato con il numero di riga, e dice per quanti secondi le altre scritture dell'app aspetterebbero. «Importa tutto» si accende dopo un'anteprima riuscita ed è tutto o niente, in due tempi: il controllo si fa fuori da ogni transazione e le scritture dentro una sola transazione, al più 50.000 righe (di tutti i fogli) e 60 secondi di scritture; oltre, non si salva niente e il motore dice di dividere il file o di importare una raccolta alla volta. Se una riga non va non si salva niente; «Carica comunque le righe buone» carica il resto.

«Ferma» interrompe un lavoro in corso: un import di più raccolte fermato non lascia niente («Import fermato: non è stato salvato niente»); per una raccolta sola i lotti già salvati restano e si tolgono con «Annulla».

«Annulla» nello storico toglie l'intero import, tutto o niente. Si ferma, senza toccare niente, e dice quali record (al più 20) se: record di altri sono collegati a quelli importati (per esempio un ordine scritto da una persona per un fornitore importato): non si forza mai; oppure se dei record sono cambiati dopo l'import: per questi c'è «Annulla comunque», con una conferma.

La scheda dice anche cosa permette l'app: «L'app lascia importare dalla console solo in: …» (campo import.consoleCollections di app.json, scritto da chi costruisce l'app; senza, la console importa come il server, in tutte le raccolte, e la scheda lo avvisa). Nell'elenco delle ricette compaiono anche quelle «pacchetto dell'app», che arrivano nella cartella release/import dell'app: si usano, non si cancellano. «Salva la ricetta» serve per rifare l'import con un clic il mese dopo.

Una cella vuota in una colonna di numeri non cancella il numero che c'è: un avviso dice che il valore è rimasto; scrivi 0 per azzerare. Per i file JSON: un elenco di oggetti, un oggetto con più elenchi (un «foglio» per elenco) o JSON Lines; le parti annidate si leggono con il punto (supplier.name).

«Prova import» per le persone

Nella home del portale, chi ha fatto l'accesso trova la tessera «Prova import»: carica un file e vede come verrebbe letto, con le stesse scelte di formato, senza importare niente. Il file sta in un deposito temporaneo del motore e si cancella da solo dopo due ore dall'ultimo uso. È utile per preparare un file prima di chiedere all'amministratore di importarlo.

17 /La home del portale

doveHome del portale (solo Proprietari)

A sinistra c'è l'anteprima della home, disegnata come la vedranno le persone; a destra le impostazioni. Il portale non cambia finché non premi «Salva».

• Scegli il layout: griglia di tessere, sezioni con un titolo (la prima volta create dai responsabili delle app) o elenco.
• Sposta le tessere trascinandole, anche da una sezione all'altra; in alternativa selezionale e usa «Prima» e «Dopo».
• Clicca un elemento dell'anteprima per cambiarlo: titolo e logo, introduzione, ricerca, una sezione o una tessera (visibile o nascosta, colore, sezione).
• Colori, sfondo e logo: il colore del testo si sceglie da solo per leggersi bene, e un avviso segnala i colori che si leggono poco. I colori di partenza sono quelli del tema di Pyrite, tessere comprese; quelli che scegli tu restano, gli altri seguono il tema chiaro o scuro.
• Controlla con «Telefono» e «Scuro» come appare su un telefono e nel tema scuro.
• «Annulla modifiche» torna all'ultima versione salvata, «Indietro» annulla l'ultimo passo, «Ripristina predefinita» riporta alla home di partenza.

Le app nuove compaiono da sole in fondo, o nella sezione «Altre applicazioni», finché non le sistemi. Nascondere una tessera cambia solo la home: l'app resta raggiungibile sulla sua porta e protetta dal suo accesso.

18 /Iscrizioni alle app: le decide chi gestisce Pyrite

Nessuna app lascia iscriversi da soli, nemmeno le pubbliche: chi gestisce Pyrite decide chi ha un utente in ogni app.

• App con accesso: le persone entrano dal portale con il loro account della rubrica; l'accesso a persone o gruppi si dà dalla console, nella pagina dell'app (Persone, Gruppi, Accessi e ruoli).
• App pubbliche: chiunque nella rete apre le pagine senza entrare. Se l'app ha bisogno di utenti (per esempio le poche persone che possono scrivere), li crea chi gestisce Pyrite nella scheda Dati dell'app, uno alla volta, con il ruolo giusto se l'app usa i ruoli. Ogni utente creato, cambiato o tolto lì lascia un evento con chi l'ha fatto. Da quella scheda nessuno può entrare nell'app come uno dei suoi utenti, e non partono email di accesso.
• La pagina d'iscrizione di un'app risponde «In questa app non ci si può iscrivere da soli: gli utenti li decide l'IT. Chiedi l'accesso a chi gestisce l'app.»
• Per la raccolta degli utenti di un'app con accesso c'è solo una riga d'informazione nei Controlli consigliati: lì gli utenti sono la copia della rubrica, e non serve fare niente.

19 /La pagina Archivio

Un Proprietario archivia un'app dalla sua pagina, scheda Configurazione: il motore la ferma, copia tutta la sua cartella (codice, dati, utenti dell'app, backup) in archivio\, controlla la copia e solo dopo toglie l'app dal motore. La pagina Archivio (per i Proprietari) elenca le app archiviate: quando e da chi, lo spazio occupato, se la copia è stata controllata, chi poteva entrare allora, la versione del motore.

• Ripristina: l'app torna nel motore spenta, com'era, con lo stesso id e la stessa porta (o nuovi, se adesso sono occupati). Se vuoi, ridà l'accesso di allora (solo alle persone e ai gruppi ancora nella rubrica). La rete in uscita torna com'era. Un'app che era in attesa di approvazione torna in attesa. Avviala dalla sua pagina dopo averla controllata. La voce resta nell'Archivio finché non la elimini.
• Elimina per sempre: elimina la copia archiviata e libera lo spazio; per confermare scrivi l'id. Non si torna indietro.
• Finisci l'archiviazione: se un file dell'app era aperto in un altro programma (Esplora file, un editor, l'antivirus), l'archiviazione si ferma a metà. La copia è fatta e controllata, l'app resta nel motore, spenta, e la console non la avvia. Chiudi quel programma, poi premi Finisci l'archiviazione nella sua voce. Se l'app è cambiata dopo la copia (per esempio dopo un ritorno con update-restore), il motore non elimina niente: l'app resta com'è, e la voce diventa una copia di allora (si può ripristinare con un altro id, o eliminare). Per archiviare l'app, archiviala di nuovo.
• Quando nel motore c'è un'app con lo stesso id di una voce, ma non ripristinata da lei (per esempio dopo un ritorno con update-restore), la pagina lo dice: sono due copie diverse, e i loro dati possono essere diversi. Prima di eliminarne una per sempre, guarda quale tenere.

20 /Backup

doveBackup per tutte le app; pagina dell'app, scheda Backup, per una sola

• Ogni notte alle 3:00 (ora del computer) il motore fa il backup di tutte le app con database in esecuzione e conserva, per ogni app, gli ultimi 7 backup automatici.
• Nello stesso giro salva anche il proprio registro: rubrica, accessi, eventi, impostazioni della home e misure. Il backup del motore compare nell'elenco con le app e si può scaricare; dalla pagina Backup si ripristinano solo le app.
• Un backup manuale si fa quando serve, per esempio prima di aggiornare un'app o di un import grande. «Backup di tutto ora» lo fa per il motore e per tutte le app insieme (solo Proprietari).
• Un Admin vede e fa i backup delle app che gestisce, una alla volta; il backup del motore lo vedono solo i Proprietari.
• I backup manuali restano finché non li elimini.
• Le app statiche non hanno database: per salvarle basta una copia della loro cartella.

Il riquadro Aggiornamenti del motore della pagina Backup elenca i punti di ripristino che il motore fa quando si cambia pyrite.exe (control\aggiornamenti) e le cartelle ritorno_<data> che update-restore mette da parte prima di tornare indietro: contengono dati personali e i dati scritti nelle app dopo l'aggiornamento, e il motore non le cancella mai da solo. Si tolgono a mano quando non servono più.

21 /Ripristino

doveBackup, comando «Ripristina» sul backup scelto

Il ripristino lo esegue il motore, in quattro passi:

1. ferma l'app;
2. salva una copia dei dati attuali in apps\<id>\state\copia_prima_del_ripristino_<data>;
3. mette al loro posto i dati del backup;
4. riaccende l'app, se era accesa. Un'app fermata con «Ferma» resta ferma anche dopo il ripristino: la riaccendi tu con «Avvia».

I dati tornano com'erano al momento del backup. Quello che è stato scritto dopo resta solo nella copia di sicurezza.

Il motore tiene le ultime 3 copie di sicurezza per ogni app (da 1 a 50, in Impostazioni del motore → Backup e ripristini): le più vecchie le toglie solo dopo un ripristino riuscito, e ogni copia tolta è scritta nello Storico del motore. Le cartelle ritorno_ del ritorno a una versione del motore, invece, non si cancellano mai da sole (vedi sopra).

22 /Password e password dimenticata

• Le password seguono le regole del motore: una lettera maiuscola e una minuscola, un numero, un carattere speciale e la lunghezza minima (di partenza 8, nelle Impostazioni del motore). Una password data da un altro (persona nuova, password provvisoria) va cambiata al primo accesso.
• Ognuno cambia la propria password nel portale (Cambia password); Proprietari e Admin anche nella console, dal menu con il loro nome.
• Un Proprietario che ha dimenticato la password: nella pagina d'accesso della console, Password dimenticata?.
  • Se il motore può mandare email (impostazioni della posta in Avanzate → Impostazioni di PocketBase, e l'Application URL con l'indirizzo vero del motore, per esempio http://SERVER:8080, non localhost; con HTTPS acceso il motore scrive da solo il collegamento in https://), la pagina manda un'email con un collegamento per scegliere una password nuova. Il collegamento vale 30 minuti, una volta sola.
  • Altrimenti la pagina mostra il comando da lanciare sul server, in un prompt dei comandi nella cartella: pyrite.exe owner reset EMAIL. Scrive una sola volta una password provvisoria; al prossimo accesso la console ne chiede una nuova, e le altre sessioni della console di quel Proprietario si chiudono.
• Admin e Utenti: una password provvisoria gliela dà un Proprietario dalla console (per le persone di livello Utente lo può fare anche un Admin); al primo accesso ne scelgono una nuova.

23 /Regole di rete

La pagina della console Regole di rete (gruppo Sistema, solo per i Proprietari) raccoglie in un posto solo tutte le regole di rete del motore. Ogni sezione si salva da sola e dice se vale subito o dal prossimo avvio. Se non cambi niente, il motore si comporta come la 0.7.4. Le regole stanno nel file control\pyrite.json. pyrite.exe network status mostra le regole in uso; a motore fermo, pyrite.exe network reset torna ai valori della 0.7.4 (il file di prima resta in control\).

Dove ascoltano le app

Ogni app ha la sua porta. La porta può restare aperta su tutta la rete (come nella 0.7.4), ascoltare solo dentro il server (le persone arrivano all'app passando dal motore, con i nomi) o ascoltare su un indirizzo che scegli. Il cambio vale subito, senza riavviare: chi stava usando un'app finisce quello che faceva. Prima di salvare «solo dentro la macchina» la pagina avvisa che le altre persone perdono l'indirizzo nome:porta. Un indirizzo che sul server non c'è non si salva. Nella stessa sezione scegli da quale porta partono le app nuove.

Un nome per ogni app

Di serie le app si raggiungono con il nome del computer e una porta (http://SERVER:8105/). In Gli indirizzi delle app puoi scegliere invece un nome per ogni app, tutti sotto un dominio usato solo per Pyrite, per esempio app.esempio.it: il portale sta lì, e ogni app ha il suo nome sotto (prenota.app.esempio.it: l'id dell'app, oppure il nome scelto nella sua scheda Esposizione). Non scrivere il tuo dominio intero (esempio.it): il certificato unico per le app varrebbe per tutti i siti di quel dominio (posta, VPN, sito).

• Un nome per app (da internet); dentro nome + porta: i nomi si usano da internet, nella rete locale gli indirizzi restano come sono.
• Un nome per app, gli stessi nomi anche dentro (Stesso nome dentro e fuori): serve un DNS interno che conosca i nomi e un certificato valido per tutti. Si accende solo se il certificato in uso copre tutti i nomi, e nella rete locale l'HTTPS diventa obbligatorio.

L'ingresso da internet

È spento finché non lo accendi. Le scelte sono Spento, Tunnel (per esempio Cloudflare), Porta aperta sul router o indirizzo pubblico e Un proxy che c'è già (nginx, IIS…).

• Tunnel o proxy: il tunnel (per esempio cloudflared su questo computer) o il proxy riceve il traffico di internet e lo passa a Pyrite. L'HTTPS lo fa chi sta davanti.
• Porta aperta: il router manda la 443 a questo ingresso (o il server ha un indirizzo pubblico) e l'HTTPS lo fa Pyrite. L'ingresso si apre solo quando l'HTTPS del motore è acceso (pagina Certificati): su internet non si serve mai niente in chiaro.
• Lì deve arrivare solo il traffico di internet: il router, il tunnel o il proxy non devono mandarlo altrove. Il motore crede all'indirizzo vero di chi arriva solo quando viene da Chi sta davanti (di serie questo computer: 127.0.0.1 e ::1), scritto nell'intestazione che scegli (CF-Connecting-IP per il tunnel, X-Forwarded-For per il proxy). Se il proxy è su un altro computer, scrivi il suo indirizzo e scegli l'indirizzo di questo computer dove l'ingresso lo aspetta.
• Da internet le persone vedono il portale e solo le app che apri a internet; la console mai (vedi Accesso).

Se internet arriva dove non deve. Se il router o un proxy manda per sbaglio il traffico di internet all'ingresso rete, Pyrite lo dice negli eventi, in Panoramica e nella pagina Regole di rete, con gli ultimi indirizzi visti. Avvisa e basta, non blocca niente: chi arriva da lì viene trattato come chi è nella rete locale. Sistema il router o il proxy.

Quali app si vedono da internet

Ogni app ha la sua scelta, Solo rete locale o Anche internet, nella scheda Esposizione della sua pagina. Le app nuove partono «Solo rete locale» (tranne quando gli utenti arrivano solo da internet).

• La decide un Proprietario, che può anche dare all'app un nome per internet (vuoto: l'id dell'app sotto il dominio delle app).
• L'Admin dell'app la può togliere da internet da solo (Togli da internet). Per aprirla la chiede (Chiedi di aprirla a internet, con una nota se vuole): la richiesta compare in Da guardare e nella scheda Esposizione, dove un Proprietario può Approvare o Rifiutare. Lo storico del motore tiene chi ha chiesto e chi ha deciso. Quando un Proprietario approva, il nome dell'app finisce nel DNS pubblico.
• Da internet un'app si apre sempre dopo l'accesso al portale.
• Indirizzo nelle email: il collegamento nelle email che le app mandano (verifica dell'indirizzo, password dimenticata) non porta più a localhost. Il motore scrive l'indirizzo giusto nell'app da solo, a ogni avvio e senza riavviarla; la scheda Esposizione lo mostra.

Le due domande e il comando pyrite.exe network setup

Due domande scelgono i valori di partenza: Dove sta il server e come ci arrivi (Da una rete privata oppure Solo da internet, per una VPS) e Da dove arrivano gli utenti (Dalla rete locale, Da internet oppure Da tutte e due, app per app). Le risposte scelgono solo i valori di partenza, e Pyrite mostra cosa cambierebbe prima che tu li applichi (Mostra cosa cambierebbe, poi Applica queste regole); dopo cambi ogni voce da sola. Si rispondono al primo avvio, dalla pagina (Rifai le domande) o, su un server senza schermo, da un terminale con pyrite.exe network setup (a motore fermo; su Windows da cmd scrivi start /wait pyrite.exe network setup, oppure dai le opzioni e --yes: network setup -h le elenca).

• Se rispondi «solo da internet» da una pagina di primo avvio aperta da un altro computer, Pyrite non ti chiude fuori: ti dice di rifarlo da un tunnel SSH (o di scegliere «rete privata»).
• Aprire il motore a tutta la rete chiede una conferma apposta, e la porta del motore non può essere quella di un'app o di un ingresso. Se il motore è partito con --http sulla riga di comando, le anteprime lo dicono: vince lui sul file.

24 /Il firewall di Windows

Perché gli altri computer aprano il portale e le app, il firewall di Windows deve lasciare entrare pyrite.exe. Pyrite ora legge com'è il firewall, lo mostra e può creare la regola. Usa una sola regola per il programma (in entrata, reti private e di dominio), non una per porta: copre il motore, ogni app e le app di domani. Si chiama Pyrite (pyrite-…), con il nome del servizio.

Quando si crea la regola

• Quando installi il servizio (pyrite.exe service install, Prompt dei comandi come amministratore) la regola si crea da sola, se Pyrite ascolta in rete. Per saltarla: pyrite.exe service install --no-firewall. service uninstall toglie solo quella regola, non le altre.
• Con il comando, in un Prompt dei comandi aperto come amministratore: pyrite.exe firewall open crea la regola (solo TCP; se la regola giusta c'è già non fa niente, e se ce n'è una con lo stesso nome che non apre, non la tocca e dice di dare close e poi open), pyrite.exe firewall close la toglie. Pyrite considera sua solo la regola con il suo nome e il suo programma: da una copia della cartella non tocca mai la regola del motore vero. pyrite.exe firewall status dice com'è il firewall e non vuole diritti di amministratore. Senza i diritti, open e close non toccano niente: scrivono il comando da rilanciare come amministratore.
• Con il tasto, dalla console: vedi sotto.
• A motore acceso il servizio non cambia mai il firewall. Gira senza diritti di amministratore, e deve restare così: un motore che potesse cambiare il proprio firewall sarebbe una porta per chi riuscisse a entrarvi.

Il riquadro «Firewall di Windows» nelle Regole di rete

In cima alla pagina Regole di rete il riquadro dice in una frase com'è il firewall per Pyrite:

• Lascia entrare Pyrite: c'è una regola attiva per il programma, per tutte le sue porte, se la rete di questo computer è segnata come privata o di dominio. Pyrite non può sapere quale rete è in uso: su una rete pubblica la regola non vale. Per il resto non c'è niente da fare.
• Solo alcune porte: la regola copre solo alcune porte; le altre, comprese quelle delle app nuove, dagli altri computer non si aprono.
• Nessuna regola: dagli altri computer non si apre niente.
• Firewall spento nelle reti private e di dominio: tutto è raggiungibile, anche senza regola.
• Deciso dalla policy aziendale: le regole locali sono ignorate, Pyrite non può aprire la rete da solo; chiedi all'amministratore di rete di consentire il programma.
• Blocco: Windows blocca tutte le connessioni in entrata, quindi le regole non valgono. Aprire non basta: il blocco va tolto nelle impostazioni del firewall di Windows. Non c'è il tasto. Se il blocco c'è solo su uno dei due tipi di rete (privata o di dominio), il riquadro dice quale: lo stato si legge allora sull'altro tipo, e una frase in più dice dove Windows blocca.
• Vietato: c'è una regola che blocca proprio questo programma. Aprire non basta: quella regola va tolta. Non c'è il tasto.
• Non si sa: Pyrite non riesce a leggere il firewall, o trova regole che non capisce (per esempio una regola che blocca tutte le porte e non si riesce a pesare). Nel dubbio non dice mai «aperto».

«Lascia entrare Pyrite» e «aperta» vogliono sempre dire «se la rete di questo computer è segnata come privata o di dominio». Sotto lo stato il riquadro elenca le app accese in rete, ognuna con la sua porta: aperta, chiusa dal firewall o non si sa. Il tasto Apri Pyrite sulla rete locale c'è solo se sono vere tutte queste cose: lo stato è «Nessuna regola» o «Solo alcune porte», chi guarda è il Proprietario, la pagina è aperta dal computer del motore, Pyrite gira con l'icona (non come servizio), c'è qualcuno davanti allo schermo, Pyrite non è stato avviato come amministratore (Windows non chiederebbe niente) e Windows su questo computer non è impostato per dare i diritti di amministratore senza chiedere (se Pyrite non riesce a leggere l'impostazione, il tasto non c'è). Quando lo premi e confermi, Windows mostra la sua richiesta, ed è per netsh.exe, un programma di Windows, non per pyrite.exe: Pyrite non gira mai con i diritti di amministratore per via del tasto. Una richiesta alla volta; nessuna finestra nera. L'esito (regola creata, non creata, richiesta rifiutata) finisce nello Storico entro due minuti; poi ricarica la pagina. Negli altri casi il riquadro non mostra il tasto ma il comando da dare a mano sul server (pyrite.exe firewall open come amministratore): quando Pyrite gira come servizio, quando nessuno è davanti allo schermo, quando Pyrite è già avviato come amministratore, quando Windows dà i diritti di amministratore senza chiedere; negli stati Blocco e Vietato nemmeno il comando basta.

I limiti

• Se il computer ha un altro firewall (di un antivirus, per esempio) o ce l'ha la rete, Pyrite non lo vede: il riquadro lo dice.
• Con una policy aziendale che decide le regole, o regole scritte in un modo che Pyrite non legge, Pyrite scrive «non si sa», mai «aperto». Il profilo di rete in uso in questo momento non si legge: Pyrite ragiona su «privato o di dominio», e i testi dicono «se la rete di questo computer è segnata come privata o di dominio».
• La regola apre solo il protocollo TCP.
• La richiesta di Windows compare nella sessione in cui gira Pyrite, non in quella di chi ha il browser (per esempio due persone collegate allo stesso server in desktop remoto): il tasto è pensato per chi è seduto al server.
• Quando Windows blocca tutto, o c'è un blocco per Pyrite, anche Panoramica e la scheda dell'app mostrano un avviso (se ci sono app accese in rete).
• Questa parte non è ancora stata provata su un Windows vero: vedi ISTRUZIONI-PROVA.html.

25 /Accesso: un solo accesso, tentativi sbagliati, la console

Un solo accesso anche con un nome per app

Quando ogni app ha il suo nome (per esempio prenota.app.esempio.it), chi apre un'app senza essere entrato passa dal portale, scrive la password una volta e torna da solo all'app. Il passaggio usa un codice che vale una volta sola, per un minuto, solo per quell'app e solo nel browser che l'ha chiesto. Nessun cookie vale per tutto il dominio. Con nome e porta (come di solito) non cambia niente.

• «Esci» chiude tutto. Esci dal portale o da un'app chiude subito anche le app con un altro nome. Lo stesso fanno Esci da tutte le sessioni, una password nuova e la persona disattivata.
• Computer condivisi. Chi entra nel portale dopo un'altra persona, dallo stesso browser, chiude anche le app che quella persona aveva aperto (quando ogni app ha il suo nome).
• Due connessioni. Chi esce su internet con due indirizzi (per esempio IPv4 e IPv6, o un proxy con più uscite) entra nelle app. Se il collegamento per entrare in un'app arriva da una connessione diversa da quella che l'ha chiesto al portale, prima di entrare compare una pagina: «Stai entrando in app come nome (email)», con Continua ed Esci. Se il nome è il tuo basta Continua. Nello Storico del motore compare un avviso, al più uno al giorno per persona e indirizzo, con i due indirizzi: di solito è la stessa persona; se succede a tante persone, il portale e le app non hanno gli stessi record DNS (per esempio l'IPv6 solo sul portale) e conviene allinearli.
• Un collegamento che non vale più. Un collegamento per entrare in un'app preparato da un altro browser, o un ingresso nel portale da una sua pagina d'accesso lasciata aperta a lungo, si ferma con «Questo collegamento per entrare nell'app non vale più»: riapri l'app dal portale. Le pagine di altri siti non possono più bloccare l'accesso al portale.

Più motori sullo stesso server

Ogni motore ha i suoi cookie, così due motori sullo stesso server (su porte diverse) non si buttano più fuori a vicenda. Chi era entrato prima dell'aggiornamento resta dentro. Attenzione: una cartella del motore copiata così com'è si porta dietro il suo identificativo, e le due copie sullo stesso server tornano a buttarsi fuori.

Tentativi sbagliati

Il motore conta le password sbagliate per ogni indirizzo vero, anche dietro un tunnel. Chi sbaglia da internet non blocca più chi è nella rete locale.

• Da internet bastano 5 errori in 15 minuti per bloccare quell'indirizzo, e 10 errori sulla stessa email (da qualunque indirizzo) bloccano quell'email per un'ora, solo da internet: dalla rete si entra sempre.
• La console ha un conto suo, separato da quello del portale.
• Le soglie si cambiano in Regole di rete, sezione Le soglie dei tentativi sbagliati.
• Il limite regge anche se i tentativi arrivano tutti nello stesso istante; da internet un'intera rete IPv6 di casa conta come un indirizzo solo. Una connessione lenta (o fatta apposta per esserlo) non blocca più l'accesso agli altri dello stesso computer o della stessa rete.
• Durante un attacco da internet il registro degli eventi non si riempie: dopo 20 blocchi in un'ora c'è un avviso solo (un testo per gli indirizzi e uno per le email). I blocchi dalla rete locale e quelli delle email delle persone della rubrica hanno sempre il loro evento; il tetto di 20 all'ora vale per ogni ingresso e solo per le email che non esistono.

La console solo da alcuni indirizzi

In Regole di rete, sezione La console, puoi dire da quali indirizzi o reti si apre la console (per esempio la VPN, oppure solo il server stesso). Vuoto vuol dire da tutta la rete. Nell'elenco ci deve essere anche l'indirizzo da cui la stai usando adesso. Da un altro indirizzo la pagina d'accesso lo dice subito, prima della password. Il portale resta aperto a tutti.

• «Solo questo computer» vuol dire ogni programma che gira sul server, app comprese.
• Se usi la console da un proxy sullo stesso server, la pagina ti dice che da lì non puoi limitare la console a un elenco, e cosa fare: lasciarlo vuoto, oppure salvarlo dal server senza il proxy o da un tunnel SSH.
• Da internet la console non c'è, nemmeno con una sessione della console aperta dalla rete locale: le chiavi della console e dei pannelli Dati valgono solo dall'ingresso da cui sono nate.
• Nel Profilo, accanto alle sessioni aperte da internet c'è scritto «da internet».

La console si chiude da sola

Dopo 30 minuti senza uso la console richiede la password (e il codice, per chi ha la doppia autenticazione). La pagina torna da sola all'accesso e scrive «Sessione chiusa dopo N minuti senza uso». Una pagina lasciata aperta su uno schermo che nessuno tocca non tiene viva la sessione: conta solo quello che fa la persona.

• Il tempo si cambia in Regole di rete, sezione La console, da 5 minuti a 12 ore. Il cambio vale subito, anche per chi è già dentro. Una sessione che si è chiusa resta chiusa, anche se poi allunghi il tempo.
• Il tetto: una sessione non dura mai più di 12 ore dall'accesso, anche se la usi di continuo. Rinnovare la chiave o cambiare la password non la fa ripartire.
• Dopo un riavvio del motore tutti rientrano (le sessioni stanno solo in memoria).
• Il limite, detto chiaro. Dentro il tempo, una console aperta su un desktop sbloccato la può usare chi si siede lì. Il tempo accorcia la finestra, non sostituisce il blocco dello schermo: blocca il desktop del server quando ti alzi (vedi La console e i livelli).
• Lavorare nel pannello Dati di un'app conta come uso della console (i gesti dentro il riquadro si ascoltano). Quando la sessione si chiude, cadono subito anche i pannelli Dati aperti da quella sessione.
• Tempi corti. Il campo dei minuti accetta anche 5: con un tempo così corto le operazioni lunghe (backup, importazioni, aggiornamenti) vanno seguite sulla pagina, perché se per tutto quel tempo nessuno la tocca la console si chiude anche con l'operazione in corso. Fa eccezione una richiesta lunga partita da un tuo gesto (un caricamento, un'esportazione): finché dura tiene viva la sessione, ma al più per 30 minuti, anche se il tempo scelto è più corto.
• Sessioni della console. Nel Profilo, riquadro Sessioni della console, ognuno vede le proprie (indirizzo, da dove, quando è stata aperta, ultimo uso) e può chiuderne una o tutte le altre. Nella scheda di una persona il Proprietario vede e chiude quelle degli altri; resta nello Storico. La chiusura è immediata. (Le sessioni che si chiudono da sole non lasciano una riga nello Storico.)

26 /HTTPS e certificati

Senza un certificato il motore lavora in HTTP: password e dati viaggiano in chiaro nella rete, e la Panoramica lo dice. Da Impostazioni del motore → Certificati (solo i Proprietari, nelle due impaginazioni della console) si accende HTTPS. Basta un certificato per il motore e per tutte le porte delle app: un certificato vale per un nome, non per una porta. Gli indirizzi di oggi (http://SERVER:8080/, http://SERVER:8105/, i segnalibri) continuano a funzionare: il motore li rimanda a https:// sulla stessa porta. I processi delle app restano in HTTP in chiaro su 127.0.0.1, dentro il server. In cima alla pagina: il modo, i nomi coperti, la scadenza, chi ha firmato, e Controlla (una prova vera di ogni porta). Prima di tutto scrivi i nomi e gli indirizzi con cui le persone raggiungono il server: il nome del computer, il nome completo nel dominio, l'indirizzo IP.

1. a. Nessun certificato (HTTP): il motore continua a lavorare in HTTP. Va bene solo per una prova.
2. b. Richiesta per la CA aziendale (Servizi certificati di Active Directory, AD CS, o un'altra CA).
   1. C'è una CA? Su un PC del dominio, nel Prompt dei comandi: certutil -dump (o certutil -TCAInfo). Una voce Config: con un server e il nome di una CA vuol dire sì. Se non trova niente, usa la CA interna (d).
   2. Crea la richiesta: la chiave privata nasce sul server e non esce mai. Scarica la richiesta (pyrite.csr).
   3. Falla firmare, su un PC del dominio, con un utente che può chiedere certificati: certreq -submit -attrib "CertificateTemplate:WebServer" pyrite.csr pyrite.cer (una finestra chiede quale CA). Se resta in attesa di approvazione: l'amministratore della CA la approva, poi certreq -retrieve RequestId pyrite.cer. Oppure con la pagina web della CA: http://SERVER-CA/certsrv → Richiedi un certificato → richiesta di certificato avanzata → incolla il testo di pyrite.csr → modello Server Web → Invia → Codificato Base 64 → Scarica certificato (o la catena, .p7b).
   4. Carica il .cer, .crt, .pem o .p7b ricevuto: il motore controlla che sia della richiesta e che copra i nomi, poi lo mette subito in uso. I PC del dominio si fidano già di una CA aziendale: niente da distribuire.
3. c. Carica un file: un .pfx/.p12 con la sua password (sia quelli che Windows esporta oggi, AES-256 con SHA-256, sia quelli vecchi, 3DES o RC2 con SHA-1), oppure .pem (certificato e chiave, in un file o in due). Il motore controlla che la chiave sia quella del certificato, che valga oggi, che sia per un server web, che la chiave sia abbastanza forte e che copra i nomi; se ne copre solo una parte chiede prima di usarlo. La password serve solo ad aprire il file e non si scrive da nessuna parte. Se un .pfx viene rifiutato lo stesso: openssl pkcs12 -in certificato.pfx -out pyrite.pem -noenc e carica il .pem.
4. d. CA interna creata da Pyrite: Crea la CA interna crea un'autorità di certificazione e il certificato del server (con i nomi, più localhost e 127.0.0.1) senza accendere HTTPS: prima distribuisci la CA sui PC, poi premi Accendi HTTPS. Il certificato del server dura 397 giorni e si rinnova da solo 30 giorni prima della scadenza, con la stessa CA. La CA può firmare solo certificati di server web e solo per questi nomi e indirizzi esatti (per un nome nuovo serve una CA nuova, e una CA nuova va ridistribuita a tutti i PC: perciò prima scegli tutti i nomi, quelli del motore e, se li vuoi, il dominio delle app, e solo dopo crea la CA): chi ne rubasse la chiave non potrebbe spacciarsi per siti di internet o per altri server del dominio, né firmare programmi. Sostituendo la CA (Nuova CA), la chiave di quella di prima si cancella subito; il suo certificato pubblico resta come riferimento (toglilo dai PC). Distribuisci pyrite-ca.cer sui PC con un criterio di gruppo:
   1. scaricalo dalla pagina (Scarica il certificato della CA);
   2. su un server con Gestione Criteri di gruppo (gpmc.msc): crea (o modifica) un oggetto Criteri di gruppo collegato all'unità organizzativa dei PC, o al dominio;
   3. Configurazione computer → Criteri → Impostazioni di Windows → Impostazioni sicurezza → Criteri chiave pubblica → Autorità di certificazione radice attendibili → tasto destro → Importa → pyrite-ca.cer → Avanti fino alla fine;
   4. i PC lo ricevono al prossimo aggiornamento dei criteri (al riavvio, o entro circa 90 minuti; subito con gpupdate /force);
   5. controlla su un PC: certlm.msc → Autorità di certificazione radice attendibili → Certificati: c'è la CA di Pyrite, con l'identificazione personale che mostra la pagina.
   A mano, su un PC fuori dal dominio: doppio clic su pyrite-ca.cer → Installa certificato → Computer locale → Colloca tutti i certificati nel seguente archivio → Autorità di certificazione radice attendibili. Edge e Chrome usano i certificati di Windows; anche Firefox nelle versioni recenti (altrimenti importalo nelle sue impostazioni).

Cosa vedono le persone la prima volta. Con un certificato di cui i PC si fidano (CA aziendale, o CA interna già distribuita): il lucchetto e nient'altro; i vecchi indirizzi http:// passano da soli a https://, e le persone rientrano una volta nel portale (l'accesso fatto con l'indirizzo in chiaro non passa). Con la CA interna non ancora sui PC il browser dice che la connessione non è privata: prima distribuisci la CA, poi accendi HTTPS, e non insegnare a cliccare oltre l'avviso. Chi arriva con un nome che il certificato non copre (per esempio il nome corto, quando nel certificato c'è solo quello completo) vede l'avviso: la pagina Certificati e la Panoramica elencano quei nomi.

Scadenze. Il motore controlla ogni giorno: in Panoramica e negli eventi a 30, 14, 7 e 1 giorno dalla scadenza; un certificato scaduto si vede in rosso. Non si spegne niente da solo.

Uscita d'emergenza. Se l'HTTPS è configurato male e la console non si apre dalla rete: dal server stesso la console si apre sempre in HTTP in chiaro su http://127.0.0.1:8080/console/. Se non basta nemmeno questo: ferma il motore (icona → Esci) e in una finestra dei comandi nella cartella scrivi pyrite.exe certificates off (pyrite.exe certificates status dice com'è impostato). Al prossimo avvio il motore lavora in HTTP; il certificato resta, e HTTPS si riaccende dalla pagina. Se HTTPS è acceso ma il certificato non si legge (per esempio dopo aver spostato il motore su un altro computer), o il file dello stato dei certificati è rovinato, dalla rete le app non rispondono in chiaro (chiuso per difetto): mostrano una pagina che dice di avvisare chi gestisce Pyrite. Con il file dello stato rovinato la pagina offre Ripara lo stato (tiene una copia del file rovinato e ricostruisce lo stato dalle cartelle, CA interna compresa); lo ripara anche certificates off. Tornando a HTTP le persone rientrano con la loro password: in HTTPS il cookie dell'accesso ha un altro nome (__Host-) e non è d'intralcio. Sul server stesso l'icona e la finestrella aprono sempre http://127.0.0.1, quindi lì nessun avviso del certificato.

Dove stanno le chiavi. In control\certificati\. Quella cartella la aprono solo SYSTEM, gli Administrators e l'account con cui gira il motore (i permessi li mette il motore, senza ereditare quelli della cartella del motore); se poi il motore gira con un altro account, dagli il controllo della cartella (icacls) o rifai il certificato. Le chiavi sono anche protette con DPAPI di Windows di questo computer: questo protegge dalla copia dei file su un altro computer, non dagli altri utenti di questo (a quello pensano i permessi della cartella). Nessuna rotta del motore le serve; non sono negli eventi, nei log, nei backup né nel punto di ripristino dell'aggiornamento del motore, e un aggiornamento del motore o update-restore non le toccano. Motore spostato su un computer nuovo: rifai il certificato (con la CA interna, una CA nuova da ridistribuire). HSTS è spento di serie; acceso (pagina, Altro), i browser che lo vedono rifiutano l'HTTP in chiaro per quel nome, su tutte le porte, per 180 giorni, anche dopo certificates off. Per tornare a HTTP dopo HSTS: spegni HSTS e lascia HTTPS acceso qualche giorno; per 180 giorni il motore dice ai browser che passano in HTTPS di dimenticare la regola.

27 /Let's Encrypt, Cloudflare e più certificati

Tutto questo sta nella pagina Certificati (HTTPS e certificati), per i Proprietari.

Più di un certificato

Pyrite può tenere più certificati e sceglie da solo quello giusto per ogni nome: prima il nome esatto, poi quello con l'asterisco, altrimenti quello «di serie». Per aggiungerne uno: Certificati → Carica un file → Aggiungilo accanto a quello di serie, per i suoi nomi. Nella stessa pagina scegli quale è quello di serie (Usalo come certificato di serie) e togli quelli che non servono. Senza certificati in più non cambia niente.

Un certificato unico per le app

Un certificato *.app.esempio.it vale per tutte le app sotto app.esempio.it (prenota.app.esempio.it, ordini.app.esempio.it…), su un solo livello, e i nomi delle singole app non finiscono nei registri pubblici dei certificati. Lo puoi avere da Let's Encrypt (qui sotto), dalla CA aziendale (scrivi *.app.esempio.it tra i nomi del motore) o dalla CA interna: con i nomi accesi la CA interna copre anche il dominio delle app e i nomi del portale. Se la CA è stata creata prima, la pagina dice che ne serve una nuova, da ridistribuire ai PC.

Let's Encrypt con Cloudflare

È la strada consigliata; vale anche per le app usate solo nella rete locale.

1. Certificati → Let's Encrypt e il DNS → apri il conto di Let's Encrypt (Apri il conto: accetta le condizioni d'uso; l'email è facoltativa).
2. Metti la chiave di Cloudflare (Chiave di Cloudflare per il controllo nel DNS, poi Prova e salva). La chiave minima: su Cloudflare, Il mio profilo → Token API → Crea token → Modifica DNS della zona (Zona · DNS · Modifica), solo la zona del tuo dominio e, se possibile, con il filtro sull'indirizzo IP pubblico del server. Funziona anche una chiave del conto. Pyrite la prova subito (scrive e toglie un record di prova) e poi non la mostra più: se ne vede solo la fine. Resta solo su questo server, protetta come le chiavi dei certificati; se il motore si sposta su un altro computer va rimessa.
3. Certificati da Let's Encrypt → Chiedi il certificato (di serie il certificato unico per le app più il portale). La pagina segue i passi mentre succedono.

Per più separazione: un dominio a parte solo per i controlli e, nel DNS del tuo dominio, un CNAME _acme-challenge.app.esempio.it verso _acme-challenge. seguito dal dominio dei controlli; con il DNS interno diviso, lo stesso CNAME anche nel DNS interno. Prima della prima richiesta vera Pyrite fa un giro con l'ambiente di prova di Let's Encrypt, così un errore non consuma i limiti. Il conto «di prova» serve solo a provare: i suoi certificati non si mettono in uso.

• Un *.app.esempio.it nel DNS (DNS dinamico, un tunnel con l'asterisco) o un DNS interno con la zona divisa non bloccano più il certificato.
• Se il firewall della rete manda le domande DNS in uscita a un suo server, Pyrite se ne accorge, aspetta un minuto e chiede il controllo (la pagina lo dice mentre succede).
• Se la zona su Cloudflare non è ancora attiva (il registrar non usa ancora i server di Cloudflare), la pagina lo dice e Pyrite non chiede niente: riprova quando Cloudflare dice «attiva».
• Se Pyrite non riesce a togliere un record di controllo dal DNS (Cloudflare non risponde), lo toglie al giro dopo; togliendo la chiave li toglie prima. Quelli che restano la pagina li elenca, da togliere a mano su Cloudflare.

Let's Encrypt con la porta 443

Senza Cloudflare, solo con la porta aperta verso Pyrite: il router manda la 443 pubblica all'ingresso internet di Pyrite (Regole di rete, porta aperta) e Pyrite risponde da sé al controllo (Chiedi con la porta 443). Fa un certificato per ogni nome su internet (il portale e le app aperte a internet), senza asterischi; con un tunnel o un proxy serve il DNS. Pyrite non usa la porta 80.

Rinnovo e avvisi

• Pyrite controlla ogni 6 ore e rinnova da solo quando resta un terzo della durata (per i 90 giorni di Let's Encrypt: a 30 giorni). Se non riesce riprova con pause sempre più lunghe; in Panoramica compare un avviso, con il motivo, solo se il problema dura e mancano meno di 14 giorni. Rinnova adesso e Smetti di rinnovarlo sono nella pagina.
• Per ogni certificato caricato a mano ci sono gli avvisi di scadenza (30, 14, 7, 1 giorno e scaduto). Quelli di Let's Encrypt si rinnovano da soli e non avvisano a 30 giorni.
• Se carichi un certificato al posto di uno di Let's Encrypt, Pyrite smette di rinnovare quello vecchio e non lo rimette in uso.
• Se Let's Encrypt scrive che un certificato va sostituito (la 0.7.5 non lo chiede da sola): Rinnova adesso nella pagina Certificati.
• Se un nome del portale o di un'app non è coperto da nessun certificato, la Panoramica lo dice, con il rimedio. Un Admin vede in Panoramica solo i nomi delle sue app.
• Ogni certificato di Let's Encrypt finisce nei registri pubblici (Certificate Transparency) con i suoi nomi; con l'asterisco si vede solo *.app.esempio.it.

L'uscita verso internet

Let's Encrypt e Cloudflare si raggiungono in HTTPS (porta 443 in uscita). Se dalla tua rete si esce con un proxy, va messo nella variabile d'ambiente HTTPS_PROXY dell'utente con cui gira Pyrite. Il controllo che il record si sia diffuso usa il DNS (porta 53 in uscita, verso i server di Cloudflare): se è chiusa, Pyrite aspetta un minuto e va avanti.

Tunnel o proxy davanti

Se l'HTTPS da internet lo fa il tunnel (per esempio Cloudflare) o un proxy, la Panoramica lo dice al posto dell'avviso «sei in HTTP». Per proteggere anche la rete locale si accende comunque l'HTTPS di Pyrite (per esempio con Let's Encrypt tramite il DNS).

Da internet con la porta aperta

Da internet solo certificati pubblici. Con la porta aperta sul router, Pyrite da internet non mostra mai il certificato della CA interna, né un certificato che contiene indirizzi interni (192.168…, 10…, 127.0.0.1) o il nome del computer senza dominio. Chi si collega senza un nome (per indirizzo IP, come fanno gli scanner di internet), con un nome che Pyrite non ha o con il nome di un'app solo interna non riceve nessun certificato: la connessione si chiude subito (un errore di connessione nel browser). Succede lo stesso per il portale e per le app aperte a internet, finché non hanno un certificato pubblico per il loro nome (Let's Encrypt, oppure uno caricato). Attenzione: se la CA interna copre quel nome, la pagina Certificati lo dà per coperto anche se da internet non si apre: controlla sempre da fuori. Così da internet non si leggono i nomi e gli indirizzi della rete interna. Dalla rete, da questo computer e con un tunnel o un proxy davanti non cambia niente.

Se qualcosa non va

• Se il file dello stato dei certificati non si legge, Pyrite non cambia niente da solo; dopo Ripara lo stato (pagina Certificati) o certificates off continua a rinnovare i certificati di Let's Encrypt.
• Tornando alla 0.7.5 dopo una 0.7.4 rimessa, anche se prima del primo avvio usi pyrite.exe certificates off, i certificati di Let's Encrypt in più tornano in uso e Pyrite continua a rinnovarli.

28 /Lo storico del motore

Gli eventi del motore (chi ha acceso un'app, chi ha dato un accesso, chi è entrato nella console, chi ha cambiato un'impostazione…) stanno ora in uno storico tutto suo, il file control\storico\storico.db, fuori dal registro. Dalla console non si cancellano e non si cambiano, nemmeno dal Proprietario: svuotare i log tecnici o rimettere un backup del registro non li tocca.

• Chi, su chi, dove. Ogni evento dice chi l'ha fatto, anche quando arriva da un'app (un file caricato, un dato ripristinato), su chi e su quale app. Per gli accessi e per le azioni dalla console c'è anche l'indirizzo da cui sono arrivati: lo vede solo il Proprietario.
• La pagina «Storico del motore» (nel menu, al posto di «Eventi»). Si filtra per periodo, app, persona (chi ha agito o su chi), tipo e gravità, e si va indietro nel tempo senza limiti. Il Proprietario vede tutto e può scaricare la vista in un file CSV (Scarica CSV; lo scaricamento resta nello storico). Un Admin vede gli eventi delle sue app, dalla 0.7.5 in poi, con i Proprietari scritti «Proprietario» (niente email dei Proprietari, niente numeri di riga). Un Utente non vede la pagina.
• Eventi fino alla 0.7.4. All'aggiornamento gli eventi della 0.7.4 si copiano nello storico, segnati «fino alla 0.7.4»: li vede solo il Proprietario. Gli originali restano nella pagina tecnica Logs, che ha il filtro Eventi fino alla 0.7.4.
• Impronte e «Controlla». Ogni riga ha un'impronta legata a quella prima: se qualcuno con le chiavi del server toglie o cambia una riga direttamente nel file, Pyrite se ne accorge (ogni notte alle 4:50, o quando un Proprietario preme Controlla) e lo dice nella Panoramica, anche dopo un riavvio. Se il file sparisce, Pyrite lo dice al riavvio. Pyrite ricorda anche, fuori dal file, l'ultima riga che ha scritto: se lo storico viene rimesso da una copia vecchia, o qualcuno aggiunge o rifà righe nel file, Controlla lo vede.
• Quanto dura. Di serie un anno. Un Proprietario può allungarlo fino a dieci anni (nella pagina dello storico o nelle Impostazioni del motore), ma non accorciarlo: nessuna strada lo permette. Ogni notte alle 4:40 si tolgono solo gli eventi più vecchi della durata scelta.
• Le copie. Lo storico non è nei backup del registro. Al loro posto, ogni notte dopo i backup delle 3:00, Pyrite ne fa una copia in control\storico\copie e tiene le ultime sette; con la copia di rete accesa, le copie vanno anche nella cartella di rete. Ogni copia, anche quella in rete, si può controllare dalla pagina: Pyrite dice se è intera e se dice la stessa cosa dello storico di adesso.
• Lo spazio. La pagina mostra quanto occupa lo storico (con le copie) e quanto crescerà in un anno, stimato dagli ultimi 30 giorni (con 50 persone, decine di MB l'anno). La Panoramica avvisa se sul disco resta meno di 1 GB o se lo storico supera un quinto dello spazio libero.
• Se non si riesce a scrivere (disco pieno, permessi) le azioni vanno avanti lo stesso: la Panoramica lo dice e gli eventi entrano nello storico appena si può. Intanto vanno anche nel file control\storico-fuori.jsonl e rientrano da soli: anche svuotando i log tecnici non si perdono. Se qualche riga di quel file di riserva si è rovinata, le altre rientrano lo stesso, lo storico lo dice con un avviso e il file con le righe rovinate resta nella cartella control, da guardare. Fermare il motore mentre rientrano tanti eventi non aspetta che entrino tutti: il resto entra al prossimo avvio.
• La console SQL delle pagine Avanzate non accetta più VACUUM (come già non accettava ATTACH).
• Tornare alla 0.7.4 (update-restore) non tocca lo storico né le sue copie; tornando alla 0.7.5 gli eventi scritti nel frattempo dalla 0.7.4 entrano nello storico, senza doppioni.
• Se copi a mano la cartella del motore, copia anche control\storico (con le copie dentro).
• Lo storico delle modifiche dei dati di un'app. Quando una persona entrata usa una funzione dell'app che scrive i dati da sé (una rotta scritta dall'app), lo storico delle modifiche dell'app porta il suo nome; i lavori pianificati dell'app e le chiamate senza accesso restano «script dell'app». Le app non vanno cambiate.

29 /Copia dei backup su una cartella di rete

I backup (ogni notte, del motore e delle app) restano sul disco del motore: se quel disco si rompe, si perdono con lui. Impostazioni del motore → Copia dei backup su una cartella di rete (Proprietari) li copia ogni giorno su una cartella di rete (un NAS, una cartella condivisa di un server) o su un altro disco.

Come si imposta

1. Sul NAS crea una cartella condivisa solo per queste copie, per esempio \\nas\backup\pyrite, chiusa a tutti gli altri (vedi Sicurezza).
2. Dai il permesso su di lei all'account con cui gira il motore (vedi Permessi).
3. Nella console: Impostazioni del motore, sezione Copia dei backup su una cartella di rete. Scrivi la cartella (\\nas\backup\pyrite; va bene anche un'altra unità come D:\copie-pyrite, ma non una lettera di un'unità di rete collegata come Z:: esiste solo per chi l'ha collegata), l'ora (di serie le 05:00, dopo i backup notturni delle 3:00: tutte e due sono ore del computer), i giorni e i mesi da tenere, accendi Copia ogni giorno e Salva. La cartella non può essere dentro la cartella del motore né in una cartella di Windows; se è sullo stesso disco del motore la pagina lo avvisa.
4. Premi Prova la cartella: scrive un file di prova, lo rilegge, lo confronta e lo toglie, e dice lo spazio libero e l'account. Poi Copia adesso e aspetta «Ultima copia riuscita».

Cosa finisce nella cartella. Il motore scrive solo in <cartella>\<NOME DEL COMPUTER>, con gli stessi percorsi che hanno nella cartella del motore: control\pb_data\backups\ (backup del registro del motore: persone, accessi, impostazioni, elenco delle app), apps\<app>\state\pb_data\backups\ (backup delle app), apps\<app>\app.json e release\ (il codice delle app), archivio\ (le app archiviate, che esistono solo lì) e pyrite-giri\ (un manifest per ogni copia: data, file, impronte SHA-256, esito). Non si copiano: le chiavi in control\certificati (sono del computer), le copie di sicurezza degli aggiornamenti delle app (control\aggiornamenti_app), i punti di ripristino del motore (control\aggiornamenti), i log e i dati di un'app fuori dai suoi backup. Nemmeno i backup automatici nativi di PocketBase (nomi che cominciano con @auto_pb_backup_, che ci sono solo se qualcuno li ha accesi nelle impostazioni native di un'app o del motore): hanno gli stessi dati dei backup notturni di Pyrite, che si copiano tutti e bastano per rimettere il registro e le app. In più c'è pyrite-versioni\<data>\: la versione di prima di un file del codice o dell'archivio cambiato o tolto nel motore.

Come copia. Ogni file tutto o niente: si scrive con un nome provvisorio, si rilegge dalla cartella e si confronta con l'originale (SHA-256), e solo allora si rinomina al nome definitivo nella cartella; gli originali non si toccano mai. Un file che c'è già uguale non si ricopia. Le copie vecchie si tolgono solo dopo una copia in cui tutti i file sono stati copiati e verificati, e solo i file che ha scritto il motore (elencati nei suoi manifest): mai altri file della cartella. Con i valori di serie restano tutti i backup degli ultimi 14 giorni (il doppio dei 7 che il motore tiene sul suo disco) e, per i 12 mesi prima, il più recente di ogni mese per ogni app e per il registro; le app archiviate restano finché sono nell'Archivio e altri 12 mesi dopo che le hai eliminate per sempre; il codice delle app è sempre quello di adesso. Una copia alla volta, al più 8 ore (i file già copiati restano: la copia dopo riparte da lì); se i backup notturni sono ancora in corso, la copia li aspetta. È il lavoro pianificato pyrite_copia_rete del motore (Avanzate → Crons). Tutti i lavori pianificati del motore contano nell'ora del computer; quelli delle app restano in UTC. Se all'ora della copia il motore è spento e l'ultima copia riuscita ha più di 24 ore, la copia parte da sola 10 minuti dopo l'avvio; una copia interrotta dallo spegnimento si vede al riavvio come non riuscita.

Protezioni. La scrittura passa senza la cache di Windows e la rilettura anche (resta solo la cache del disco o del NAS). Un backup già copiato non si sovrascrive mai: se nel motore un backup con lo stesso nome è cambiato (disco rovinato, virus che cifra), la copia non riesce, lo dice, e quella in rete resta com'era. Il codice delle app e l'archivio invece cambiano: la versione di prima va in pyrite-versioni\ e resta lì per i giorni da tenere, e nella cartella dell'app c'è sempre il codice di adesso. Un'app registrata senza la sua cartella nel motore, o una cartella del motore che non si legge, fanno fallire la copia e fermano la pulizia (la copia in rete serve proprio per rimetterle). A ogni copia una parte dei file già in rete (fino a 2 GB, prima quelli verificati da più tempo) si rilegge per intero: una copia rovinata di un file che il motore ha ancora si rifà (evento), una di un file che il motore non ha più è un evento d'errore. La copia non legge e non scrive mai attraverso un collegamento (giunzione) nella cartella di rete, e controlla dove sta davvero ogni file che scrive. La pulizia non si fa se l'ora del computer è prima dell'ultima copia o più di 48 ore dopo l'ultima riuscita (con un avviso: controlla l'ora; se l'ora di adesso è giusta e il manifest più recente viene da un orologio sbagliato, copialo fuori da pyrite-giri\ e poi cancellalo), toglie solo i file con i nomi e nelle cartelle che il motore scrive, e lascia sempre almeno gli ultimi 3 backup verificati di ogni app e del registro. Con lo spazio finito la copia toglie prima le copie scadute che il motore non ha più e riprova una volta. Se nella cartella del computer ci sono le copie di un altro motore con lo stesso nome del computer, la copia si ferma senza scrivere niente: scegli un'altra cartella.

Se non riesce si vede. Un evento d'errore con il motivo in parole semplici (cartella non raggiungibile, accesso negato con l'account del motore e cosa fare, spazio finito, impronta diversa, troppo lenta); nella Panoramica un riquadro rosso quando la copia è accesa e l'ultima riuscita ha più di 26 ore (o non ce n'è mai stata una); nella pagina Backup una riga con l'ultima copia riuscita (verde; gialla se l'ultima copia non è riuscita, rossa dopo 26 ore).

Permessi sulla cartella

Nessuna password salvata: la copia gira con l'account del motore (lo mostra la sezione, e lo dice la prova).

• Computer nel dominio, motore che gira come SYSTEM (l'attività pianificata del motore, o un servizio): in rete il motore è l'account del computer, DOMINIO\NOME$. Nella condivisione e nella scheda Sicurezza della cartella dai Modifica a quel computer (in Windows: Aggiungi → Tipi di oggetto → Computer; sul NAS scegli il computer dal dominio).
• Motore che gira come un utente (attività pianificata con un utente, «Esegui indipendentemente dalla connessione degli utenti»): dai Modifica a quell'utente. La sua password la tiene Windows (Utilità di pianificazione), non Pyrite.
• Computer fuori dal dominio, motore come SYSTEM: SYSTEM in rete non ha un account. Fai girare l'attività del motore con un utente che il NAS conosce.
• Un account a parte con una password sua, solo per la copia: per ora non si può. Serve una cassaforte dei segreti nel motore (prevista più avanti); fino ad allora il permesso va all'account del motore.

Sicurezza

• I backup contengono tutti i dati delle app, le persone e le impronte delle loro password: la cartella è solo per l'account del motore e per chi gestisce Pyrite. Non una cartella che tutti collegano.
• Accendi le istantanee del NAS (versioni in sola lettura fatte a orari fissi e tenute per settimane): un virus che cifra i file e arriva alla condivisione (l'account del motore lì può scrivere) non le può toccare.
• Meglio un NAS in un'altra stanza, e ogni tanto una copia che resta scollegata.
• Chi cambia la cartella (un Proprietario) fa presentare il motore a quel server con il suo account (in rete, di solito, l'account del computer): un server scelto apposta potrebbe raccoglierne le credenziali di rete. Per questo ogni cambio della cartella è un evento (chi, da quale cartella a quale), e la cartella non può essere questo stesso computer (localhost, 127.0.0.1, il suo nome o i suoi indirizzi) né una condivisione amministrativa (C$, ADMIN$). Dai il livello di Proprietario solo a chi serve e guarda gli eventi delle impostazioni.

Rimettere un'app da una copia

1. Nella cartella di rete apri <NOME DEL COMPUTER>\apps\<app>\state\pb_data\backups\ e scegli il backup (il nome ha data e ora: auto_20261105_030000.zip).
2. Copialo (copia, non spostare) nella stessa cartella del motore: apps\<app>\state\pb_data\backups\.
3. Console → Backup → l'app: il file è nell'elenco. Premi Ripristina: il motore ferma l'app, tiene una copia dei dati di adesso (state\copia_prima_del_ripristino_…), rimette il backup e riaccende l'app.

Un'app di cui manca tutta la cartella: copia apps\<app>\ dalla cartella di rete (codice e backup) in apps\ del motore, poi Rileggi cartelle, avviala e ripristina il backup come sopra. Un'app archiviata: copia archivio\<voce>\ di nuovo in archivio\ del motore e usa la pagina Archivio.

Ripristinare il registro del motore

Il registro (persone, livelli, gruppi, chi entra in quale app, impostazioni, elenco delle app) si ripristina a motore fermo. Quello che è cambiato dopo quel backup (persone nuove, password, accessi) si perde.

1. Scegli il backup: in control\pb_data\backups\ del motore, oppure nella cartella di rete (<NOME DEL COMPUTER>\control\pb_data\backups\).
2. Icona vicino all'orologio → Esci.
3. Copia l'intera cartella control\pb_data in una cartella fuori dal motore (copia, non spostare: è la strada per tornare indietro).
4. Estrai lo zip (clic destro → Estrai tutto) in una cartella fuori dal motore: dentro ci sono data.db, auxiliary.db e forse storage\.
5. In control\pb_data cancella data.db-wal, data.db-shm, auxiliary.db-wal, auxiliary.db-shm se ci sono, poi copia i file estratti sopra quelli di control\pb_data (sostituisci). Non toccare control\pb_data\backups.
6. Avvia il motore e controlla persone e app nella console. Se qualcosa non va: Esci, rimetti la cartella copiata al passo 3, riavvia.

Un computer nuovo (il disco vecchio non c'è più)

1. Metti pyrite.exe (la stessa versione) in una cartella nuova; non avviarlo ancora.
2. Nella cartella del motore crea a mano la cartella control\pb_data (il motore non è ancora partito, quindi non c'è). Poi dalla cartella di rete <NOME DEL COMPUTER VECCHIO>\ copia nella cartella del motore control\pb_data\backups\ (dentro la control\pb_data appena creata), apps\ e archivio\ (non pyrite-giri\ e pyrite-versioni\).
3. Rimetti il registro dal suo backup più recente (passi 4 e 5 qui sopra).
4. Avvia il motore: le app ci sono, con il loro codice e i dati vuoti. Per ogni app con database: Backup → l'app → il backup più recente → Ripristina.
5. HTTPS: il certificato non è nella copia (le sue chiavi sono del computer vecchio): rifallo dalla pagina Certificati. La copia di rete si riaccende con il registro e scrive nella cartella con il nome del computer nuovo.

30 /Spostare Pyrite su un altro computer

Vale quando il computer vecchio funziona ancora e vuoi Pyrite su uno nuovo. Se il disco vecchio non c'è più, vedi sopra Un computer nuovo (il disco vecchio non c'è più).

1. Spegni prima il motore (icona vicino all'orologio → Esci, oppure ferma il servizio), così nessun file viene scritto durante la copia.
2. Copia tutta la cartella di Pyrite, non solo pyrite.exe: deve contenere control, apps e logs. Il registro del motore (persone, livelli, gruppi, elenco delle app) è il file control\pb_data\data.db: senza, il motore nuovo parte vuoto.
3. È più sicuro fare uno ZIP della cartella ed estrarlo sul computer nuovo in una cartella nuova e vuota, invece di copiare file per file.
4. Come si riconosce una copia riuscita. Al primo avvio la pagina del primo Proprietario non compare: si arriva alla pagina d'accesso e le persone ci sono. Se compare la pagina del primo Proprietario, la copia è incompleta (di solito manca control\pb_data\data.db). Non creare niente: chiudi il motore e rifai la copia.
   Copia incompleta? Lo dice Pyrite stesso. Se manca control\pb_data\data.db ma la cartella mostra una vita passata (vecchi log, app con i loro dati, lo storico), la pagina del primo Proprietario mostra un avviso e non va avanti finché non spunti «Sì, è un motore nuovo»; lo stesso avviso è scritto nella finestra del motore e in logs\engine.log (vale anche quando Pyrite parte dall'icona o come servizio: allora lo dicono il log e la pagina); da terminale, pyrite.exe owner create EMAIL si ferma e chiede --new-engine. Se è una copia: chiudi il motore e rifai la copia, con tutta la cartella. Solo se è davvero un motore nuovo, spunta la casella (oppure usa --new-engine): lo Storico lo registra. L'avviso sparisce da solo quando il registro è tornato. Un motore davvero nuovo, con la cartella vuota, non mostra nessun avviso.
5. Che cosa è legato al computer e va rifatto. Il certificato HTTPS: le sue chiavi sono del computer vecchio, quindi lo rifai dalla pagina Certificati (vedi sopra Un computer nuovo e HTTPS e certificati). La doppia autenticazione: la chiave dei codici si apre solo sul computer che l'ha fatta, quindi chi l'aveva risulta «da riattivare» (vedi La chiave e i backup).
6. Impostazioni di Windows da rifare. Il firewall: la regola è per il file su quel computer. Sul computer nuovo pyrite.exe firewall status dice se c'è; pyrite.exe firewall open (da amministratore) la crea, e l'installazione del servizio la crea da sola (vedi Il firewall di Windows; Windows può chiederla anche al primo avvio, vedi Primo avvio). E l'avvio con Windows (il menu dell'icona, il servizio o l'attività pianificata: vedi Pyrite come servizio di Windows).
7. Tieni spento il computer vecchio, con la sua cartella intatta, per qualche giorno. È la strada per tornare indietro. Non avviare i due motori insieme nella stessa rete: una cartella copiata così com'è porta con sé il suo identificativo, e le due copie si buttano fuori dall'accesso (vedi Più motori sullo stesso server).

31 /Lingue, colori e tema

• Console, portale e pagine del motore sono in inglese e in italiano; la lingua si sceglie in fondo alle pagine e vale per tutto il motore. Le schermate native di PocketBase (Log, Avanzate, le schede dei record) restano in inglese.
• Portale, console, pagine d'accesso e di primo avvio e la finestrella vicino all'orologio hanno un tema chiaro e uno scuro. Chiaro: bianco con un filo di salvia, pulsanti grafite, collegamenti acqua scura. Scuro: sfondo quasi nero e testo crema. Le tessere delle app, i grafici e i colori degli stati (errore, avviso, riuscita) restano i colori di Pyrite. I collegamenti sono sempre sottolineati.
• Il tema (chiaro, scuro o come il sistema) scelto nel portale vale anche nella console, e viceversa.
• Se la home del portale è stata personalizzata, i colori scelti restano; gli altri seguono la tavolozza nuova.

32 /Aggiornare dalla 0.7.6

Si fa come l'aggiornamento dalla 0.7.5, descritto qui sotto: si sostituisce solo pyrite.exe, il motore fa da solo il punto di ripristino e aggiorna tutto o niente. Questa volta non ci sono controlli da fare sugli script delle app. Dopo l'aggiornamento la finestrella dell'icona e pyrite.exe -v devono dire alpha 0.7.7 (vedi «Cosa controllare dopo l'aggiornamento» qui sotto). Per tornare indietro: update-restore, come descritto qui sotto.

Che cosa cambia da solo

• La console si chiude dopo 30 minuti senza uso. Avvisa chi la usa: troverà più spesso la pagina d'accesso. Il tempo si cambia nelle Regole di rete (da 5 minuti a 12 ore); vedi La console si chiude da sola.
• Nelle Regole di rete compare il riquadro Firewall di Windows; Carica app, la scheda di un'app e Panoramica avvisano quando una porta è chiusa dal firewall.
• Le app in attesa di approvazione mandano un'email ai Proprietari, se la posta è impostata (vedi App in attesa di approvazione).
• Se in una copia della cartella manca il registro, Pyrite dice «copia incompleta?» (vedi Spostare Pyrite su un altro computer).
• Chi rientra. Chi era nel portale resta dentro: nessuno deve rientrare nel portale. La console invece chiede di nuovo l'accesso, come a ogni riavvio del motore.

Che cosa non cambia finché non lo decidi tu

• Il firewall resta com'è. L'aggiornamento non crea né toglie nessuna regola. Se il servizio è già installato e vuoi la regola, dai pyrite.exe firewall open da amministratore (come servizio il tasto nel riquadro non c'è: vedi Il firewall di Windows).
• Indirizzi, porte, accessi, persone, dati e app restano dove sono.

33 /Aggiornare dalla 0.7.5

Il motore si aggiorna sostituendo solo pyrite.exe: stesso nome, stessa cartella. Indirizzi, porte, accessi, dati, app, persone e impostazioni restano dove sono, e nessuno viene buttato fuori: chi era entrato nel portale resta dentro. Per sapere che programma hai, pyrite.exe -v scrive la versione. Questo capitolo vale anche per arrivare alla 0.7.7 dalla 0.7.5; chi viene dalla 0.7.5 legga anche Aggiornare dalla 0.7.6: quello che cambia da solo vale anche per lui.

1. Controlla il pyrite.exe nuovo: in PowerShell, nella sua cartella, Get-FileHash .\pyrite.exe -Algorithm SHA256 deve dare la stessa impronta SHA-256 che hai ricevuto insieme al file (nel messaggio o nella pagina da cui l'hai scaricato). Se è diversa, non avviarlo.
2. Ferma il motore: icona vicino all'orologio → Esci. Aspetta che l'icona sparisca. Se Pyrite gira come servizio di Windows: net stop pyrite-… (vedi Pyrite come servizio di Windows).
3. Tieni il programma vecchio: copia pyrite.exe (copia, non spostare) in una cartella fuori dal motore, con il nome della versione che hai, per esempio C:\Pyrite-0.7.5\pyrite.exe. Serve per tornare indietro.
4. Copia il pyrite.exe nuovo nella cartella del motore, sopra quello vecchio (stesso nome). Non cambia nient'altro.
5. Prima di aggiornare, fai i controlli sugli script delle app elencati qui sotto (Controlli da fare prima) e fai una copia dell'intera cartella a motore fermo.
6. Fai doppio clic su pyrite.exe (o net start pyrite-…). Prima di cambiare qualcosa il motore controlla la cartella (nessun altro motore acceso su di essa, file che può scrivere, spazio libero sul disco a sufficienza) e fa da solo un punto di ripristino: una copia dei dati del motore e dei dati e delle impostazioni delle app, in control\aggiornamenti\ (si tengono gli ultimi 2). Poi aggiorna. Tutto o niente: se qualcosa va storto, o il computer si spegne a metà, il motore rimette tutto a posto dal punto di ripristino e lo scrive in logs\engine.log; riavvialo per riprovare, oppure rimetti il pyrite.exe vecchio. Se un controllo non passa, il motore non cambia niente, non parte e dice perché (vedi Problemi).
7. Se Windows mostra la finestra «Sicurezza di Windows», scegli Reti private e consenti, come al primo avvio. Di solito non la chiede, perché il file ha lo stesso nome nella stessa cartella.
8. Le sessioni della console sono tenute solo in memoria: dopo il riavvio, Proprietari e Admin rientrano con la stessa email e la stessa password. Dalla 0.7.5 tutti rientrano una volta nel portale (vedi sotto); dalla 0.7.6 chi era nel portale resta dentro.

Con molte app e tanti dati il primo avvio ci mette di più, perché il punto di ripristino copia prima i dati. Serve spazio libero sul disco pari ai dati: se non c'è, il motore non cambia niente e dice quanto ne serve.

Cosa cambia dalla 0.7.5

• Per chi usa Pyrite quasi niente. Al primo avvio il motore fa da solo il passaggio ai ruoli e scrive un riepilogo: chi è Proprietario, chi è Admin e di quali app. Lo trovi nello storico e nel file control\passaggio-ruoli.txt. Nessuno guadagna o perde permessi, e password e sessioni della console restano quelle di prima. Chi era Admin resta «Admin (come nella 0.7.5)» (vedi La console e i livelli).
• Dalla 0.7.5, dopo l'aggiornamento tutti rientrano una volta nel portale. Succede anche a chi viene dalla 0.7.4. Dalla 0.7.6 alla 0.7.7 non succede: chi era nel portale resta dentro. Succede di nuovo, una volta, se il motore viene spostato su un altro computer, se la cartella control\biglietti si perde, o se si torna alla versione di prima con update-restore. Niente altro cambia per chi usa il portale. La cartella control\biglietti non va copiata insieme ai backup del registro: chi avesse il registro e la chiave apribile potrebbe fabbricare un biglietto d'accesso.
• Se togli un'app o un ruolo a un Admin mentre ha la console aperta, la console lo fa uscire: rientra e trova la situazione nuova. Se gli dai un'app in più, resta dentro e la vede subito. Quando si elimina un'app, i suoi Admin rientrano (nella 0.7.5 restavano dentro).
• Chi smette di essere Admin perde subito le app che gestiva. Nella 0.7.5 in certi casi restavano da parte e tornavano quando la persona ridiventava Admin: adesso vanno assegnate di nuovo.
• Chi amministra una sola unità vede una frase diversa: se scrive l'email di un Proprietario (creando una persona o cambiando un'email) legge «Questa email non si può usare. Chiedi al Proprietario» al posto di «Questa email c'è già nella rubrica». Il Proprietario trova nello storico chi l'ha scritta.
• Prima dell'accesso il portale mostra solo le applicazioni ad accesso libero; quelle che chiedono l'accesso compaiono dopo che la persona è entrata. La frase «Ci sono altre N applicazioni a cui non hai accesso» non c'è più: il portale non dice quante altre applicazioni esistono.
• A chi non vede i Proprietari il motore non inoltra più le risposte che non riesce a controllare (oltre 8 MB, o compresse in un formato diverso da gzip): al loro posto un errore che lo dice. Rimedio: chiedere meno righe per volta, o farlo fare a un Proprietario.
• La pagina Certificati e la Panoramica avvisano quando un'app o il portale è aperto su internet ma ha solo il certificato interno: da internet quel nome non si apre, serve un certificato pubblico (Let's Encrypt o caricato).

Controlli da fare prima sugli script delle app

La 0.7.6 stringe il recinto degli script (vedi Che cosa può fare un'app). Prima di aggiornare, per ogni app, cerca nei file di apps\NOME-APP\release\pb_hooks e pb_migrations queste cose. Se non ne trovi, per quell'app l'aggiornamento non cambia niente.

• $apis.static con una cartella fuori dalla cartella dell'app (un'altra app, una cartella del server): ora serve solo cartelle dentro la cartella dell'app. Se la chiamata è scritta fuori da ogni funzione (la forma più comune), lo script dà errore al caricamento. I file vanno portati dentro la cartella dell'app.
• $app.onServe, $app.restart, $app.restoreBackup e $app.rootCmd (anche $app.execute() e $app.start()): per gli script non esistono più. Lo script che usa uno di questi nomi riceve un errore («Object has no member '…'»). Contano solo se chiamati su $app o e.app.
• unbind, unbindAll, .bind( chiamato su un aggancio dell'app ($app.on…().bind(), onSend( della posta e unsafeWithoutHooks: non esistono più. Attenzione: .bind( è anche una funzione normale di JavaScript (funzione.bind(this)), che va bene.
• Comandi SQL con ATTACH o DETACH (erano già vietati, ora non c'è più modo di farli passare), VACUUM scritto insieme ad altri comandi o con un commento, e colonne chiamate attach, detach o vacuum senza virgolette.
• Percorsi che cominciano con una barra (/release/x.json, \state\x.db): prima si leggevano dalla cartella dell'app, ora sono la radice del disco e vengono rifiutati. Si scrivono senza la barra davanti (release/x.json, state/x.db).
• Chiamate di rete verso il motore o verso un'altra app: il registro apps\NOME-APP\logs\network.log (e network.1.log, network.2.log) tiene solo gli ultimi 12 MB. Cerca le righe con "ip":"127., "ip":"::1" o l'indirizzo del server, e quelle con localhost o il nome del server in "host", e guarda "port": se è la porta del motore o di un'altra app, fermati e decidi prima di aggiornare (dopo l'aggiornamento quella chiamata sarebbe rifiutata). Se è la porta dell'app stessa o un altro programma del server, continua a funzionare.
• Altre cose che non ci sono più: $os.getenv("HTTP_PROXY") e simili rispondono vuoto; new Command(...) non esiste; .db() sul database ($app.concurrentDB().db() e simili) dà un oggetto vuoto: si usano newQuery(...), select(...) e le altre funzioni di sempre; $filesystem.local(...) e $os.dirFS(...) su cartelle che contengono collegamenti o giunzioni non leggono né scrivono più i file dall'altra parte. Per chi usa le app non cambia niente: le copie di sicurezza dalla console di PocketBase funzionano come prima.
• Campi o raccolte con i nomi del motore. Controlla che persone, gruppi e app non abbiano un campo proprio che si chiama units o unit, e che non ci siano raccolte proprie chiamate orch_units o orch_roles. Se ci sono, l'aggiornamento si ferma, dice quale nome è già preso e non cambia niente: riavvia la versione di prima, rinomina il campo (o la raccolta) e aggiorna di nuovo.

Che cosa succede a un'app che usa una di queste cose: lo script riceve un errore in inglese e quella parte dell'app non funziona. Il motore smette di riavviare un'app con un problema nei file e riprova quando i file cambiano o quando premi Riavvia; la scheda Stato e gli eventi dicono perché. Se qualcosa non va dopo l'aggiornamento, la via di ritorno è update-restore (qui sotto).

Se arrivi dalla 0.7.4

• La prova dal vivo di questa versione è stata fatta sull'aggiornamento dalla 0.7.6 e dalla 0.7.5, con il ritorno indietro (update-restore) in tutti e due i casi. Il passaggio diretto dalla 0.7.4 non è stato provato: se sei ancora alla 0.7.4, è più sicuro passare prima dalla 0.7.5 (aggiorna alla 0.7.5, controlla che tutto funzioni, poi aggiorna alla 0.7.7).
• La rete resta com'è finché non la cambi: Pyrite crea control\pyrite.json con i valori della 0.7.4 (motore su 0.0.0.0:8080, app su tutta la rete, indirizzi con il numero di porta, nessun ingresso internet). Li cambi nelle Regole di rete.
• Il biglietto d'accesso del portale ha un nome per ogni motore, e dalla 0.7.6 i biglietti della 0.7.4 non fanno più entrare nessuno (tutti rientrano una volta). Chi torna alla 0.7.4 deve rifare l'accesso. Su un computer condiviso conviene che ognuno prema Esci da tutte le sessioni nel profilo (o cambi la password).
• Dall'ingresso internet in porta aperta, un nome che non ha un certificato pubblico dà un errore di connessione, invece del certificato interno (vedi Let's Encrypt, Cloudflare e più certificati).
• Il codice del primo avvio si legge nella finestra del motore, e in logs\engine.log quando Pyrite parte dall'icona (vedi Primo avvio). Lo storico del motore prende gli eventi della 0.7.4, segnati «fino alla 0.7.4» (vedi Lo storico del motore); la pagina «Eventi» ora è «Storico del motore».

Cosa controllare dopo l'aggiornamento

• Clicca l'icona vicino all'orologio: la finestrella dice alpha 0.7.7 e le app sono accese. pyrite.exe -v scrive «Pyrite alpha 0.7.7»; nelle proprietà di pyrite.exe (tasto destro → Proprietà → Dettagli) la versione del file è 0.7.7.0.
• Il controllo sicuro: nella pagina Backup del motore il riquadro Aggiornamenti del motore dice «Questa cartella: alpha 0.7.7, aggiornata il … (prima: alpha 0.7.6, o alpha 0.7.5 se vieni da lì)» e mostra il punto di ripristino come «completato».
• L'evento «Motore aggiornato da alpha 0.7.6 alla versione alpha 0.7.7 in … s. Punto di ripristino: …» (da alpha 0.7.5 se vieni da lì) si vede negli Ultimi eventi della Panoramica solo subito dopo l'avvio: dopo pochi secondi le partenze delle app e gli accessi lo spingono via. Lo ritrovi nello Storico del motore.
• Apri il file control\passaggio-ruoli.txt (o il riepilogo nello storico) e controlla chi è Proprietario e chi è Admin di quali app. Poi apri Persone e Gruppi con un Admin e vedi che siano come prima.
• Apri il portale e un'app con accesso, come una persona normale (rientrando, se hai l'accesso).

Tornare alla versione di prima

Per tornare indietro, lancia sempre pyrite.exe update-restore --yes PRIMA di rimettere il pyrite.exe vecchio. Se rimetti solo l'exe, il motore vecchio prende la cartella per un aggiornamento: fa un punto di ripristino nuovo e toglie il più vecchio, e dopo un altro passaggio avanti non c'è più il punto con i dati di prima dell'aggiornamento.

1. Ferma il motore: icona → Esci (o net stop pyrite-…).
2. Apri un prompt dei comandi (cmd) nella cartella del motore (in PowerShell scrivi .\pyrite.exe al posto di pyrite.exe) e lancia pyrite.exe update-restore. Non cambia niente: dice soltanto che cosa farebbe. Quale punto di ripristino, di quando, e quali scelte fatte dopo l'aggiornamento annulla: le persone tolte o bloccate dopo tornano attive, le password cambiate dopo tornano quelle vecchie, tornano i Proprietari, gli accessi e le app tolti dopo. Il piano dice anche chi torna Admin, chi non lo è più e a chi tornano le app gestite di prima; chi perde i ruoli di Admin Persone e Admin App ricevuti dopo l'aggiornamento; le unità create dopo e le persone create dopo, che tornando indietro non ci saranno più; chi perde la doppia autenticazione e chi resta fuori perché la chiave del server è stata rifatta dopo il punto. Scrivi tutto. Il prompt torna subito (vedi Per i tecnici): aspetta l'ultima riga, «Non è stato cambiato niente. Per andare avanti: pyrite.exe update-restore --yes».
3. Lancia pyrite.exe update-restore --yes e aspetta la riga «Fatto in … s»: rimette i dati del motore e i dati e le impostazioni delle app com'erano prima dell'aggiornamento. Quello che è cambiato dopo l'aggiornamento (anche quello che le persone hanno scritto nelle app nel frattempo) si copia prima da parte, in control\aggiornamenti\ritorno_…; il motore quella copia non la cancella mai (la pagina Backup la elenca): cancellala a mano quando non ti serve più.
4. Solo dopo, rimetti il programma vecchio: copia C:\Pyrite-0.7.5\pyrite.exe (o quello della tua versione di prima) nella cartella del motore, sopra quello nuovo, e avvialo. Se invece riavvii la versione nuova, si aggiorna di nuovo, con un punto di ripristino nuovo.
5. Controlla: la finestrella dice la versione di prima; nella pagina Backup, riquadro Aggiornamenti del motore, il punto dell'aggiornamento è «rimesso con update-restore»; le app sono accese con i dati di prima dell'aggiornamento.
6. Nella console rifai quello che il comando ha elencato: blocca di nuovo le persone, cambia di nuovo le password, togli di nuovo Proprietari, accessi e app. Le persone rifanno l'accesso al portale, una volta.

A motore acceso, update-restore rifiuta e non cambia niente. Un'app archiviata dopo l'aggiornamento torna tra le app, con i dati di prima dell'aggiornamento, e la sua copia archiviata resta in archivio\ con i dati di quando è stata archiviata: sono due copie, quindi prima di eliminarne una guarda quale tenere. Un'app installata dopo l'aggiornamento esce dal motore (i suoi file restano nella copia messa da parte). Un'app aggiornata da zip dopo l'aggiornamento del motore torna alla versione di prima, e il suo «Torna alla versione di prima» non è più offerto: la copia di sicurezza di quell'aggiornamento tiene i dati del giro che si è lasciato indietro (resta sul disco, segnata come superata; il piano di update-restore la elenca). Gli stessi passi sono nella pagina Backup del motore, riquadro Aggiornamenti del motore. update-restore non tocca i backup, le copie fatte prima di un ripristino, i log, lo storico del motore e le sue copie.

I certificati: la 0.7.4 usa solo il certificato di serie. Se dalla 0.7.5 torni alla 0.7.4 e poi di nuovo avanti, i certificati di Let's Encrypt tornano da soli (o Pyrite li richiede); il conto di Let's Encrypt e la chiave di Cloudflare restano. I certificati in più caricati a mano vanno ricaricati se la 0.7.4 ne ha tolto la cartella.

34 /Fermare le app e il motore

• Un'app: nella sua pagina della console premi Ferma (e Avvia per riaccenderla). Chi la apre intanto vede la pagina «app ferma».
• Il motore: icona vicino all'orologio → Esci (nel menu o nella finestrella; anche lo spegnimento di Windows lo ferma nello stesso modo ordinato). Le app si fermano con lui; al prossimo avvio il motore riaccende tutte le app, tranne quelle che hai fermato dalla console.
• Per far partire il motore da solo all'avvio di Windows usa Avvia con Windows nel menu dell'icona.

35 /Pyrite come servizio di Windows

Oltre che con l'icona vicino all'orologio, Pyrite può girare come servizio di Windows. Come servizio parte da solo quando si accende il server, anche se nessuno si collega; se si ferma per un guasto, Windows lo fa ripartire dopo un minuto (fino a tre volte al giorno); quando il server si spegne, Pyrite ferma le app in ordine. Non ha icona né finestre: la console si apre dall'indirizzo di sempre, anche dal server stesso (un doppio clic su pyrite.exe apre la console nel browser). I messaggi principali sono anche nel Visualizzatore eventi di Windows (Registri di Windows → Applicazione, origine pyrite-…), oltre che in logs\engine.log.

Su un server, non avviare Pyrite con il doppio clic da un utente amministratore di Windows. Avviato così, il motore e gli script di tutte le app girano con i diritti pieni sul server. Il modo previsto è il servizio di Windows, che gira con un account suo (vedi sotto).

Installare, guardare, togliere

• Installare: apri il Prompt dei comandi come amministratore, vai nella cartella di Pyrite e scrivi pyrite.exe service install. Il servizio si chiama pyrite- più l'identificativo del motore (lo scrive pyrite.exe network status).
• Vedere come sta: pyrite.exe service status.
• Toglierlo: pyrite.exe service uninstall. Poi un doppio clic su pyrite.exe riporta l'icona.
• All'installazione Pyrite spegne «Avvia con Windows» dell'icona (non serve più) e, se l'icona è accesa, il servizio aspetta che la chiudi (icona, Esci) e prende il suo posto.
• Aggiornare: ferma il servizio (net stop pyrite-…), sostituisci pyrite.exe, riaccendilo (net start pyrite-…).

L'account e la cartella

• Il servizio gira con un account suo, che può scrivere solo nella cartella di Pyrite. Se la copia dei backup va su un altro disco di questo server, dai i permessi a quell'account sulla cartella della copia, oppure installa con pyrite.exe service install --localsystem.
• La cartella deve essere chiusa. Il servizio fa girare pyrite.exe con un account con molti permessi, quindi Pyrite si installa come servizio solo se nessun utente senza i permessi di amministratore può cambiare la sua cartella. Se la cartella è aperta (succede con una C:\Pyrite creata a mano), pyrite.exe service install si ferma e scrive i comandi da copiare per chiuderla; oppure metti Pyrite in C:\Program Files\Pyrite. Pyrite deve stare su un disco del server, non su una cartella di rete.
• Il firewall. L'installazione crea la regola del firewall di Windows per il programma (in entrata, reti private e di dominio), perché il comando si dà come amministratore; service install --no-firewall la salta e service uninstall la toglie. Se non riesce a crearla, scrive il comando da lanciare a mano. A motore acceso il servizio non cambia mai il firewall. Dettagli: Il firewall di Windows.

Anche il primo avvio può chiedere la stessa scelta, con la tua sessione (icona) o come servizio: vedi Primo avvio.

36 /Avvio senza nessuno collegato

Il modo migliore per far partire Pyrite senza nessuno collegato è il servizio di Windows (vedi Pyrite come servizio di Windows). Se preferisci un'attività pianificata di Windows, o il servizio non si può usare, si fa così. L'attività si prepara una volta sola. Dopo averla preparata, provala come descritto in «I limiti dell'attività pianificata».

Cosa preparare

• Un account per il motore, meglio uno dedicato (un account di dominio come DOMINIO\svc-pyrite, o uno locale) e non amministratore. Deve avere il diritto Accedi come processo batch (Criteri di protezione locali → Criteri locali → Assegnazione diritti utente). Se il PC è nel dominio e la copia dei backup va su un NAS, un account di dominio è la strada più comoda (vedi Permessi sulla cartella).
• La cartella del motore, per esempio C:\Pyrite (con dentro pyrite.exe; i dati, le app e i log nascono accanto). L'account ha bisogno di Modifica su tutta la cartella (icacls C:\Pyrite /grant "DOMINIO\svc-pyrite:(OI)(CI)M"); gli altri utenti no. Non metterla sotto C:\Program Files né in una cartella del profilo di un utente.
• Se l'HTTPS è già acceso e finora il motore girava con un altro account (per esempio il tuo, con il doppio clic): la cartella control\certificati non eredita i permessi della cartella del motore e il nuovo account non la apre. Dai a quell'account il controllo della cartella (icacls C:\Pyrite\control\certificati /grant "DOMINIO\svc-pyrite:(OI)(CI)F") oppure rifai il certificato; vedi HTTPS e certificati, «Dove stanno le chiavi». Finché non lo fai le app non rispondono dalla rete.
• La cartella di rete della copia dei backup, se la usi: Modifica allo stesso account sulla condivisione e sulla cartella, come scritto in Copia dei backup su una cartella di rete (l'account del motore, qui quello dell'attività, è quello che scrive lì).
• Il firewall, da sistemare a mano: senza nessuno collegato la finestra «Sicurezza di Windows» del primo avvio non compare mai, e Windows blocca gli altri computer. Il modo più semplice: pyrite.exe firewall open in un Prompt dei comandi aperto come amministratore (controlla con pyrite.exe firewall status; vedi Il firewall di Windows). Oppure a mano: aggiungi una regola in entrata per il programma C:\Pyrite\pyrite.exe, TCP, profilo privato (o dominio), per esempio New-NetFirewallRule -DisplayName "Pyrite" -Direction Inbound -Protocol TCP -Program "C:\Pyrite\pyrite.exe" -Action Allow -Profile Domain,Private. Una regola sul programma copre il motore (8080) e la porta di ogni app, quindi vale anche quando aggiungi app. Rifalla se il file viene sostituito con un altro in un'altra cartella (la regola è per quel percorso).
• Il primo Proprietario: crea il Proprietario una volta sola, prima di lasciare il PC da solo: dalla pagina di primo avvio, che si apre da un altro computer della rete con il codice che Pyrite scrive in logs\engine.log, oppure dalla riga di comando (pyrite.exe owner create EMAIL, che scrive una password provvisoria).

L'attività pianificata

Il comando è C:\Pyrite\pyrite.exe --autostart --unattended.

• --autostart è quello che scrive Avvia con Windows nel menu dell'icona: il motore parte sull'indirizzo di sempre, 0.0.0.0:8080 (raggiungibile dalla rete), scrive le sue scritte in logs\engine.log e non apre nessun browser.
• --unattended dice che nessuno è davanti allo schermo: il programma che avvia il motore non mostra nessuna finestra di messaggio (nessuno potrebbe chiuderla), non apre il browser e non mostra fumetti; il motivo di ogni problema va in logs\engine.log (la prima riga dice perché lavora senza nessuno: «no one at the screen») e il programma finisce con un codice di uscita diverso da 0. In un'attività che gira «indipendentemente dalla connessione dell'utente» il programma capisce da solo che non c'è nessuno, ma scrivi lo stesso l'opzione: serve anche per un'attività che parte quando un utente entra e nessuno guarda lo schermo. Con qualcuno davanti allo schermo e senza --unattended tutto funziona come al solito (finestre, browser).

In PowerShell come amministratore:

$c = Get-Credential 'DOMINIO\svc-pyrite'   # una finestra chiede la password, così non resta nella cronologia dei comandi
$a = New-ScheduledTaskAction -Execute 'C:\Pyrite\pyrite.exe' -Argument '--autostart --unattended' -WorkingDirectory 'C:\Pyrite'
$t = New-ScheduledTaskTrigger -AtStartup
$t.Delay = 'PT1M'    # un minuto dopo l'avvio, così la rete (e il NAS) è pronta
$s = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) `
       -ExecutionTimeLimit ([TimeSpan]::Zero) -StartWhenAvailable -AllowStartIfOnBatteries `
       -DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew
Register-ScheduledTask -TaskName 'Pyrite' -Action $a -Trigger $t -Settings $s `
       -User $c.UserName -Password $c.GetNetworkCredential().Password -RunLevel Limited

La stessa cosa a mano: Utilità di pianificazione → Crea attività; Generale: l'account, Esegui indipendentemente dalla connessione dell'utente, lascia senza la spunta Non memorizzare la password (la password la tiene Windows); Trigger: All'avvio, ritardo di 1 minuto; Azioni: avvia il programma C:\Pyrite\pyrite.exe, argomenti --autostart --unattended, inizia in C:\Pyrite; Impostazioni: Se l'attività non riesce, riavvia ogni 1 minuto, fino a 3 volte; togli la spunta a Arresta l'attività se è in esecuzione da più di; Se l'attività è già in esecuzione: non avviare una nuova istanza. Non usare Esegui con i privilegi più elevati: il motore non ne ha bisogno.

Codici di uscita e cosa succede

Se termini l'attività (Stop-ScheduledTask, o «Termina» nell'Utilità di pianificazione), il codice di uscita non lo sceglie Pyrite: lo decide Windows.

Per farla partire senza riavviare il PC: Start-ScheduledTask -TaskName Pyrite. Stop-ScheduledTask termina l'attività, ma non è provato che il motore si fermi in modo ordinato: il motore si chiude con ordine solo quando il programma che lo avvia riceve la richiesta di chiudere o Windows si spegne, e terminare un'attività di solito chiude il processo subito. Quindi, prima di fermarla, ferma le app dalla console (pulsante Ferma nella pagina di ogni app) e, se hai appena cambiato qualcosa, fai un backup dalla pagina Backup; dopo il riavvio guarda la Panoramica e logs\engine.log. Un motore avviato a mano e l'attività non possono girare insieme sulla stessa cartella: un secondo motore sulla stessa cartella non parte (codice di uscita 3 senza nessuno davanti allo schermo).

I limiti dell'attività pianificata

• Nessuna icona. Non c'è l'icona da guardare e non c'è «Esci». Per sapere se il motore è vivo, apri http://SERVER:8080/ da un altro PC (è comunque il controllo migliore: non fidarti solo dello stato dell'attività), oppure leggi logs\engine.log (le scritte del motore, 10 MB, le ultime 3 copie).
• Controlla il riavvio. Dopo aver preparato l'attività, provala: ferma il processo del motore e occupa la porta 8080 con un altro programma. Controlla soprattutto che l'attività riparta davvero dopo un codice di uscita 1: non è detto che «Se l'attività non riesce, riavvia» guardi il codice di uscita del programma e non solo il mancato avvio. Se non riparte, il riavvio automatico non c'è: serve un controllo dall'esterno (http://SERVER:8080/ da un altro PC).
• I backup sul NAS richiedono che l'account dell'attività sia noto al NAS: con un account locale del PC che il NAS non conosce, la copia non riesce a scrivere (lo dice la prova della pagina). Vedi Permessi sulla cartella.
• Aggiornare funziona come sempre (ferma l'attività, sostituisci pyrite.exe, riavvia l'attività); la regola del firewall è per il percorso del file: se il percorso resta lo stesso non c'è niente da cambiare.
• Se il PC lo usa anche qualcuno che entra in Windows, non accendere in più Avvia con Windows: un secondo motore non parte, ma crea confusione.

37 /Avvertenze dell'alpha

38 /Limiti noti

Sono le cose che la 0.7.7 non fa, o fa solo in parte. Stanno qui perché tu le sappia prima di fidartene.

• La console non si raggiunge mai da internet in questa versione, qualunque siano le impostazioni.
• Lo storico del motore non è una garanzia assoluta. Chi ha i file del server e sa come lavora Pyrite può ancora riscrivere gli eventi. Pyrite è fatto per accorgersi dei cambi nel file (Controlla, ogni notte), ma non può promettere di accorgersi di tutti.
• I registri del tunnel e dei proxy sono dati riservati. Chi li legge in tempo reale ed è più veloce del browser della persona può usare il suo collegamento per entrare in un'app una volta. È un caso quasi teorico (deve leggere il collegamento e usarlo nei pochi millesimi di secondo prima che arrivi il browser della persona): la persona vede «Questo collegamento per entrare nell'app non vale più» e riapre l'app, e nello Storico del motore resta sempre l'evento «codice usato una seconda volta», più l'avviso con i due indirizzi. Chi legge quei registri e ha anche il permesso sull'app può mandare alla persona un collegamento preparato con la propria utenza, nei 10 minuti al più in cui lei ha aperto l'app senza essere ancora entrata nel portale: la persona vede la pagina con il nome di chi ha mandato il collegamento, e perché il trucco riesca deve accettare un nome che non è il suo e premere Continua. Se preme Esci nello Storico del motore resta un evento, se continua l'avviso. Se chi ha mandato il collegamento e la persona escono su internet dallo stesso indirizzo (la stessa rete) la pagina non compare.
• Due copie della stessa cartella sullo stesso server si buttano fuori a vicenda dall'accesso, perché la copia si porta dietro l'identificativo del motore.
• Se il motore non riesce a leggere il suo identificativo (il file control\pyrite.json è rovinato o non si può scrivere all'avvio), lavora con i nomi della 0.7.4. Quando l'identificativo c'è di nuovo, chi era entrato nel frattempo rientra una volta. Nessun rischio.
• La chiave di Cloudflare resta solo su questo server. Se il motore si sposta su un altro computer, va rimessa. Pyrite non chiede da sola a Let's Encrypt le revoche: se un certificato va sostituito, premi Rinnova adesso.
• Let's Encrypt con la porta 443 fa un certificato per ogni nome (niente asterischi), e con un tunnel o un proxy serve il DNS.
• L'account del servizio di Windows scrive solo nella cartella di Pyrite: per una copia dei backup su un altro disco del server, dagli i permessi, oppure usa --localsystem. Finché il servizio è installato, la cartella control\certificati non è leggibile dall'utente dell'icona: è voluto, e vale finché togli il servizio. A motore acceso il servizio non cambia il firewall (vedi Il firewall di Windows).
• Un Admin non vede più in Panoramica i nomi del portale negli avvisi dei certificati, solo i nomi delle sue app.
• Il recinto intorno agli script non è un muro. Riduce molto quello che lo script di un'app può fare, ma è dentro il programma: lo script gira nello stesso processo del motore di quell'app, con lo stesso utente di Windows. La garanzia piena per le app di terzi sarà un utente di Windows per ogni app, in una versione futura. Fino ad allora le app di clienti diversi su un motore vanno bene se gli script li scrive o li controlla chi gestisce il motore (vedi Che cosa può fare un'app).
• Chiamate di un'app all'indirizzo pubblico del server. L'immagine del profilo presa da un accesso OAuth2 e le chiamate di un'app verso l'indirizzo pubblico o il nome pubblico di questo server partono senza il segno del motore: arrivano al motore come una richiesta qualunque da fuori. Un indirizzo di rete appena preso dal server resta senza segno fino a un minuto (le schede di rete si rileggono ogni 60 secondi). Un'app che si chiama con il suo nome dall'ingresso internet riceve «non esiste». Un tuo proxy che gira sullo stesso computer può avere l'indirizzo 127.0.0.1: per il motore le sue richieste sono «da questo computer».
• Un tunnel o un proxy puntato direttamente sulla porta di un'app (invece che sull'ingresso internet del motore) fa leggere all'app l'indirizzo del proxy e non quello del visitatore. La strada giusta è l'ingresso internet, con chi sta davanti dichiarato nelle regole di rete.
• Un altro programma sulla porta interna di un'app. Chi prende la porta interna di un'app ferma può fare una cosa sola: impedire all'app di partire, e si vede (vedi Che cosa può fare un'app). La finestra in cui un altro programma può prendere la porta, dall'avvio del processo all'apertura della porta, è stata misurata su un PC scarico: circa 0,2-0,3 secondi.
• Doppia autenticazione. Non vede chi scrive la tabella delle persone senza passare dai salvataggi di PocketBase (SQL diretto, la console SQL di un Proprietario). Chi ha il server in mano (il registro e la chiave apribile, con l'utente che fa girare il motore) può ancora fabbricare un biglietto d'accesso. Il conto dei codici sbagliati si azzera al riavvio del motore.
• Unità, e che cosa si può ancora vedere. Chi amministra molte unità vede nello storico meno, mai di più: con 11 unità solo le persone che stanno in al più 5 unità, e così via a scendere. Un Admin App legge ancora, nello storico della sua app, i vecchi eventi di una persona poi spostata in un'altra unità. Sulle API native, un filtro sul campo delle unità può dire se una persona sta anche in un'altra unità, se si conosce l'id di quell'unità. Quando una pagina porta l'email di un Proprietario, anche una persona che si chiama come lui è scritta «Proprietario». Spostare un'app o un gruppo e dare un accesso nello stesso istante può lasciare un accesso a cavallo fra due unità: il motore lo segnala all'avvio.
• Pagine che non dicono ancora tutto. Il riepilogo di un pacchetto caricato non dice in quale unità nascerà l'app. Lo spostamento di un'app non toglie da solo le persone che restano senza più niente nell'unità di partenza. Il menu «persona» dello Storico legge al più 1000 persone.
• Non ancora provato con le cose vere (un tunnel vero, Let's Encrypt e Cloudflare veri, il servizio di Windows su un server vero, Windows Server, un DNS diviso).

39 /Per i tecnici

I comandi

Si scrivono in una finestra dei comandi aperta nella cartella del programma (in PowerShell scrivi .\pyrite.exe invece di pyrite.exe); con un comando dopo il nome, il programma scrive in quella finestra. Senza nessun comando (pyrite.exe da solo) parte come con il doppio clic, con l'icona.

• I comandi owner funzionano a motore spento o acceso: il motore acceso legge la modifica in pochi secondi. Se il motore sta facendo proprio in quel momento un backup o un ripristino, chiedono di riprovare tra qualche minuto.
• Il motore non ha il comando superuser di PocketBase: l'account di PocketBase del motore è un account tecnico con una password casuale, che il motore gestisce da solo e con cui non entra nessuno. Per la prova locale di una singola app (pyrite.exe worker …) c'è ancora: vedi lo standard per gli agenti.
• Il programma è fatto per non aprire finestre: per questo cmd e PowerShell, quando lo scrivi a mano, non lo aspettano. Il prompt torna subito e le scritte del programma arrivano sotto, mescolate al prompt; Ctrl+C ferma comunque il motore in modo ordinato. Per farlo aspettare come un programma normale: in cmd start "" /wait /b pyrite.exe serve --http=0.0.0.0:8080; in PowerShell Start-Process -Wait -NoNewWindow .\pyrite.exe -ArgumentList 'serve','--http=0.0.0.0:8080' (serve senza --http ascolta solo da questo computer, sulla porta 8090); dentro un file .bat cmd aspetta già da solo.
• Il codice d'uscita è quello vero solo quando il comando viene aspettato: %ERRORLEVEL% dentro un file .bat o dopo start "" /wait /b; in PowerShell (Start-Process -Wait -NoNewWindow -PassThru .\pyrite.exe -ArgumentList …).ExitCode.
• I comandi che il motore suggerisce (nella console, nella pagina d'accesso, nel terminale) usano il nome vero del file del programma: se rinomini pyrite.exe, lo seguono.
• Nel terminale il motore scrive Company portal: …/ ed Engine console: …/console/; anche la riga Dashboard: …/_/ scritta da PocketBase porta alla console.
• In Gestione attività i processi sono: uno per l'icona, uno per il motore, uno per ogni app con database. Non chiuderli da lì: si ferma tutto con Esci.
• Se nelle impostazioni di PocketBase c'è un elenco di «Superuser IPs», resta in vigore: la console si apre solo dai computer dell'elenco, e gli altri ricevono un messaggio chiaro. I Proprietari lo vedono sotto Avanzate, con un avviso e Svuota la lista.
• L'email per la password dimenticata parte solo per i Proprietari attivi, al massimo una ogni 2 minuti per persona (e al più 5 richieste ogni 15 minuti dallo stesso indirizzo); la pagina risponde allo stesso modo per ogni email, quindi non dice chi è nella rubrica.

40 /Problemi e licenze

• Una persona con la doppia autenticazione non entra più nella console: il motore è stato spostato o il file della chiave si è perso. Un Proprietario gliela toglie con pyrite.exe owner two-factor-off EMAIL e la persona la attiva di nuovo (vedi Doppia autenticazione).
• L'aggiornamento si ferma e dice che un nome è già preso: un campo chiamato units o unit, o una raccolta chiamata orch_units o orch_roles, è di una delle tue app. Non è stato cambiato niente: vedi Controlli da fare prima.
• Un'app è «failed» o «unhealthy» e dice che sulla sua porta interna risponde un altro programma: vedi Che cosa può fare un'app.
• La console dice che è per Proprietari e Admin: il tuo account ha il livello Utente; chiedi a un Proprietario.
• Dopo un riavvio del motore la console chiede di nuovo l'accesso: è normale, le sessioni stanno solo in memoria.
• Il motore dice «Ci sono troppe sessioni aperte sul motore: riprova fra poco»: ci sono troppe sessioni della console o troppi pannelli Dati aperti insieme (c'è un tetto per ogni persona e uno per tutto il motore). Chiudi quelli che non servono (Profilo → Sessioni della console → chiudi tutte le altre) o riprova dopo un minuto.
• La console chiede di nuovo la password dopo pochi minuti: si chiude da sola dopo il tempo senza uso scelto nelle Regole di rete (di serie 30 minuti), e comunque dopo 12 ore (vedi La console si chiude da sola).
• La pagina del primo Proprietario mostra un avviso di copia incompleta e non va avanti: in una cartella già usata manca il registro control\pb_data\data.db. Se stai spostando Pyrite, chiudi il motore e rifai la copia; spunta «Sì, è un motore nuovo» solo se lo è davvero (vedi Spostare Pyrite su un altro computer).
• Il riquadro «Firewall di Windows» mostra il comando e non il tasto: il tasto c'è solo in pochi casi, apposta (vedi Il firewall di Windows); dai il comando sul server come amministratore.
• Un'app non parte e dice che è in attesa di approvazione: prima la deve approvare un Proprietario.
• Il motore dice che l'aggiornamento non è iniziato: leggi il messaggio (nella finestra «Pyrite non è riuscito a partire.» che mostra Pyrite, con le ultime righe del log, e in logs\engine.log: la console non si apre). Non è stato cambiato niente: un altro motore acceso sulla stessa cartella, un file che non si può scrivere, o poco spazio libero sul disco. Sistema e riavvia il motore.
• Un'app non funziona più dopo l'aggiornamento: guarda la sua scheda Stato e gli eventi: la console dice perché e cosa fare. Quando il problema è nei file dell'app (uno script, una migrazione), il motore smette di riavviarla e riprova da solo quando i file cambiano, oppure quando premi Riavvia. Per tornare indietro vedi Tornare alla versione di prima.
• Un'app non parte e dice che la sua archiviazione non è finita: nella pagina Archivio premi Finisci l'archiviazione nella sua voce (vedi La pagina Archivio).
• La pagina d'iscrizione di un'app non funziona: gli utenti delle app li decide chi gestisce Pyrite (vedi Iscrizioni alle app).
• La pagina di primo avvio dice che si apre solo con un indirizzo del motore, o chiede un codice: usa l'indirizzo IP o il nome del computer, e leggi il codice nella finestra del motore o in logs\engine.log (vedi Primo avvio).
• La pagina d'accesso della console dice che si apre solo da alcuni indirizzi: usa uno degli indirizzi ammessi (per esempio la VPN, o il server stesso), oppure chiedi a un Proprietario di cambiare l'elenco nelle Regole di rete (vedi Accesso).
• Da internet il browser mostra un errore HTTPS: il nome non ha un certificato che lo copra, oppure non è un nome che Pyrite serve da internet. Vedi Let's Encrypt, Cloudflare e più certificati.
• Dagli altri computer non si vede niente: controlla che pyrite.exe sia consentito sulle reti private nel firewall di Windows (il permesso è per il file: un file del programma con un altro nome o in un'altra cartella lo richiede di nuovo): pyrite.exe firewall status dice com'è, e lo mostra il riquadro «Firewall di Windows» nelle Regole di rete (vedi Il firewall di Windows). Usa l'indirizzo IP o il nome di questo computer.

Pyrite contiene PocketBase (licenza MIT, © Gani Georgiev) e altri componenti open source: le loro licenze sono in THIRD-PARTY-NOTICES.txt. Pyrite is an independent project built on PocketBase; it is not affiliated with or endorsed by PocketBase or its author. (Pyrite è un progetto indipendente costruito su PocketBase; non è affiliato a PocketBase né al suo autore, che non lo approvano né lo sostengono.)