Documentazione · riferimento

Concetti

Le parole usate nella console e nelle guide, con il significato che hanno in questo prodotto.

01 /Il percorso di una richiesta

Quando una persona apre un'app con login, la richiesta fa questo giro:

BrowserLa persona apre l'app dal portale.http://SERVER:8101/
Porta d'ingressoIl motore controlla la sessione e l'accesso all'app.porta pubblica 8101
Istanza dell'appIl PocketBase dell'app applica le sue regole.porta interna 9101, solo dal server
Dati dell'appDatabase e file caricati.apps\<id>\state\pb_data

Per un'app statica il giro è più corto: il motore serve le pagine direttamente dalla cartella release\public dell'app, senza istanza e senza database.

02 /Motore e app

Motore: Il programma pyrite.exe avviato normalmente. Tiene il registro delle app, la rubrica, gli accessi, le misure e gli eventi. Avvia e sorveglia le app e serve il portale e la console, di solito sulla porta 8080. I suoi dati stanno in control\pb_data.
App: Un'applicazione ospitata dal motore. Sul disco è una cartella dentro apps, con la scheda, il codice e, se l'app ha dati, la cartella dei dati.
Scheda: Il file app.json nella cartella dell'app. Dice al motore come si chiama l'app, di che tipo è, su che porta risponde, se serve il login, quali ruoli ha e quali strumenti del motore usa. La cambia solo l'amministratore, cioè un Proprietario dalla console oppure chi lavora sul server: gli script dell'app la possono solo leggere. Tutti i campi sono nel riferimento della scheda.
Tipo: Statica, PocketBase oppure PocketBase con automazioni. Dice cosa contiene l'app e se le serve un'istanza.
Istanza: Il processo PocketBase che fa girare una singola app con i suoi dati. È lo stesso eseguibile del motore, lanciato dal motore in modalità worker, e non va avviato a mano. Ogni istanza ascolta su una porta interna (la porta pubblica più 1000: 9101, 9102 e così via) che risponde solo sul server.
Porta d'ingresso: Il motore risponde sulla porta pubblica di ogni app e inoltra le richieste all'istanza. In questo modo decide chi entra e conta richieste, errori e traffico senza toccare l'app. Se l'app è ferma, risponde con una pagina che lo spiega.
Portale: La pagina per tutti, all'indirizzo del motore, con le tessere delle app e degli strumenti come «Prova import». Da qui le persone entrano ed escono. Il suo aspetto si cambia dalla console, nella pagina «Home del portale».
Console del motore: L'area riservata all'amministratore, su http://SERVER:8080/console/ (anche /_/, l'indirizzo del pannello di PocketBase, porta lì), con la sua pagina d'accesso. Dentro c'è il pannello di PocketBase del motore, con i colori di Pyrite e con in più le sezioni per gestire app, persone e backup. Ci entrano solo i Proprietari e gli Admin.
Pannello di un'app: Il pannello di PocketBase di una singola app, ridotto a raccolte e record. Si apre solo dalla console, nella scheda «Dati» della pagina dell'app; direttamente sulla porta dell'app non si apre. «Console» è quella del motore, «pannello» quello di un'app.

03 /Persone e permessi

Rubrica: L'elenco centrale delle persone, con email, password e stato (attiva o disattivata). Sta nel motore e vale per tutte le app.
Gruppo: Un insieme di persone che hanno bisogno degli stessi accessi, come «Soci». Una persona può stare in più gruppi.
Livello nella console: Quanto una persona può fare nella console. I livelli sono quattro: Proprietario (tutto), Admin Persone (le persone e i gruppi della sua unità), Admin App (le sue app) e Utente (solo portale e app, nella console non entra); chi era Admin prima resta «Admin (come nella 0.7.5)». I ruoli li dà un Proprietario nella scheda della persona (vedi La console e i livelli). Non c'entra con i ruoli dentro le app.
In attesa di approvazione: Lo stato di un'app caricata da un Admin con «Carica app»: è installata ma non si avvia e non compare nel portale finché un Proprietario non la approva.
Accesso: Il permesso di entrare in un'app, dato a una persona (accesso diretto) o a un gruppo. Dice solo chi entra, non con quale ruolo: basta un accesso, diretto o tramite un gruppo, per entrare.
Ruolo: Il livello di una persona dentro un'app, per esempio «responsabile» o «magazziniere». I ruoli possibili li dichiara la scheda dell'app, dal più al meno potente. Il ruolo si gestisce dentro l'app e non dipende dai gruppi: lo cambia l'amministratore (un Proprietario o un Admin che gestisce l'app) nella scheda «Accessi e ruoli» o, se l'app lo prevede, chi ha il ruolo più alto. Cosa può fare ciascun ruolo lo decidono le regole e il codice dell'app.
Livello base: Il ruolo che una persona riceve la prima volta che entra in un'app (defaultRole nella scheda; se manca, il ruolo meno potente). Dopo la prima entrata il motore non tocca più il ruolo.
Account nell'app: L'utente che esiste dentro l'istanza di un'app. Il motore lo crea quando la persona entra dal portale per la prima volta, con la stessa email e lo stesso nome della rubrica e il livello base. Email, nome e password dall'app non si cambiano: l'identità è bloccata.
Accesso unico: Login una volta sola nel portale, poi le app si aprono già autenticate. La sessione è legata al nome o all'indirizzo del server, per questo portale e app vanno aperti con lo stesso indirizzo. Se ogni app ha il suo nome (Regole di rete), un solo accesso vale anche tra i nomi diversi. «Esci» nel portale chiude la sessione per tutte le app.
Amministratore tecnico: Un account da amministratore che esiste dentro ogni app, con una password casuale che nessuno conosce. Lo usa solo il motore per gestire l'app. Entrare come amministratore direttamente sulle porte delle app non è possibile.
Account tecnico del motore: Il superuser di PocketBase del motore, con una password casuale che non è scritta da nessuna parte. Lo usa solo il motore: gli amministratori entrano nella console con il loro account della rubrica.

04 /Dati e continuità

Backup: Un archivio dei dati di un'app con database. Automatico ogni notte alle 3:00 (ora del computer), con gli ultimi 7 conservati, oppure manuale. Lo stesso giro notturno salva anche il registro del motore.
Ripristino: Rimettere i dati di un backup al posto di quelli attuali. Lo esegue il motore: ferma l'app, salva una copia di sicurezza, sostituisce i dati e la riaccende, se era accesa.
Copia di sicurezza: La copia dei dati presenti prima di un ripristino, in apps\<id>\state\copia_prima_del_ripristino_<data>. Si cancella a mano.
Archiviazione: Togliere un'app dal servizio conservandola per intero in archivio\<id>_<data>, dopo aver verificato la copia. Dalla pagina Archivio della console la si ripristina (torna ferma, com'era) o la si elimina per sempre.
Strumento del motore: Un componente pronto, scritto in Go dentro il motore, che gli script delle app usano per i lavori pesanti, per esempio l'import e l'export Excel e CSV, i PDF, le foto, le numerazioni, lo storico delle modifiche, le statistiche e i lavori pianificati (otto strumenti pronti). Si attiva app per app, nella scheda Configurazione (solo i Proprietari). L'elenco è nella pagina «Strumenti» della console.
Ricetta: Le impostazioni di un import salvate per riusarle: come leggere il file, in quale raccolta caricarlo, quale colonna va in quale campo e quale chiave riconosce i record già presenti.
Misure: Memoria, CPU, database, richieste, errori, scritture, accessi riusciti e negati, tempo medio di risposta e traffico, raccolti ogni minuto per ogni app e conservati 30 giorni.
Punto di ripristino: La copia che il motore fa da solo quando si sostituisce pyrite.exe (in control\aggiornamenti): permette di aggiornare tutto o niente e di tornare indietro con pyrite.exe update-restore.
Copia di rete: La copia giornaliera dei backup su una cartella di rete (un NAS) o un altro disco, controllata file per file con SHA-256. Si imposta in Impostazioni del motore.
Certificato e HTTPS: Con un certificato il motore e tutte le porte delle app rispondono in https; senza, in http. Il certificato viene dalla CA aziendale, da un file .pfx o .pem o da una CA interna creata da Pyrite. Le chiavi stanno in control\certificati.
Rete in uscita: Gli indirizzi che gli script di un'app possono chiamare: quelli dichiarati in network nella scheda. Il motore li blocca o, in modo «Avvisa», li conta soltanto.
Profilo: La pagina personale di ogni persona: nome, lingua, tema, password, impaginazione della console ed «Esci da tutte le sessioni». Il motore lega la persona all'utente dentro ogni app per ID, non per email.
Lavori pianificati: I lavori che le app o il motore fanno da soli a certe ore. Il motore li registra e nella pagina «Lavori pianificati» mostra quando partono, com'è andata l'ultima volta, pausa e «Avvia ora».
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 c'è una sola unità, «Tutta l'azienda» (vedi Più clienti su un motore: le unità).
Doppia autenticazione: Un codice a sei cifre, preso da un'app sul telefono, che si scrive dopo email e password: per la console e per il portale, con dieci codici di riserva (vedi Doppia autenticazione).
Sessione della console: Il tempo in cui una persona resta dentro la console. Si chiude da sola dopo 30 minuti senza uso (da 5 minuti a 12 ore, nelle Regole di rete) e non dura mai più di 12 ore; nel Profilo ognuno vede e chiude le proprie (vedi La console si chiude da sola).
Recinto degli script: Il limite che il motore mette agli script di un'app: file, programmi, database e rete. Riduce molto quello che uno script può fare, ma è una difesa dentro il programma, non un muro (vedi Che cosa può fare un'app).
Regole di rete: La pagina della console, solo per i Proprietari, con le regole di rete del motore: dove ascoltano le app, un nome per ogni app, l'ingresso da internet, i tentativi sbagliati, da quali indirizzi si apre la console e il firewall di Windows (vedi Regole di rete).
Barra laterale: Il menu della console per Proprietari e Admin: le app (5 di serie, da 3 a 15 a scelta, con «Altre app» e un ordine personale che segue la persona) e le pagine del motore in due gruppi, Servizi e Sistema. Con l'impaginazione «Menu in alto» sta in cima alla pagina.
Importa persone e gruppi: La pagina della rubrica che carica da un modello Excel gruppi, persone e accessi alle app, con anteprima, tutto o niente e le password provvisorie in un file che si scarica una volta. Solo aggiunta.
Import intelligente («Tutto il file»): La scelta della scheda «Importa» che carica un file con più fogli (o un JSON con più elenchi) in più raccolte in una volta: propone foglio → raccolta, colonne → campi e l'ordine dai collegamenti, mostra l'anteprima per raccolta e carica tutto o niente (al più 50.000 righe e 60 secondi di scritture). «Annulla» toglie l'intero import.
Note di consegna: Il file in radice del pacchetto di un'app (DELIVERY.md, README.md, NOTES.md o CONSEGNA.md) che spiega all'amministratore cosa fa l'app e cosa controllare. «Carica app» ne mostra l'inizio, e un aggiornamento da zip le sostituisce.
Storico del motore: L'elenco degli eventi del motore: avvii, arresti, errori, backup, ripristini, accessi al portale, modifiche, importazioni. Stanno in un file tutto loro, che dalla console nessuno cancella né cambia. I Proprietari li vedono tutti nella voce «Storico del motore» della barra laterale; gli Admin vedono quelli delle loro app (vedi Lo storico del motore).

05 /Le cartelle

cartella del programma\
├── pyrite.exe              il programma
├── README.html             leggimi della cartella (e THIRD-PARTY-NOTICES.txt, le licenze)
├── control\pb_data\        dati del motore (registro, rubrica, eventi, backup del motore)
├── control\aggiornamenti\  i punti di ripristino dell'aggiornamento del motore (e le copie ritorno_)
├── control\storico\  lo storico del motore (e le sue copie)
├── control\pyrite.json  le regole di rete del motore
├── control\doppia\  la chiave dei codici della doppia autenticazione
├── control\certificati\    le chiavi e lo stato dell'HTTPS (aperta solo a SYSTEM, Administrators e all'account del motore)
├── logs\                   engine.log, le scritte del motore
├── apps\
│   └── <id>\
│       ├── app.json        la scheda
│       ├── release\        il codice: pagine, hook, migrazioni
│       ├── state\          i dati veri (pb_data) e le copie di sicurezza: l'unica cartella in cui scrivono gli script dell'app
│       └── logs\           l'output del processo
└── archivio\               le app archiviate

Codice e dati sono separati: il codice di un'app si sostituisce senza toccare i suoi dati.