KEPLIN Docs

Impostazioni della piattaforma

Le sezioni di amministrazione della piattaforma, una alla volta: processi, limiti, antivirus, email, allarmi, OpenTelemetry, intelligenza artificiale, autenticazione delle app, app mobile, modelli, file inutilizzati, installazione e open source.

Le Impostazioni sono il pannello di controllo dell'intera installazione. Non sono le impostazioni di un'app — quelle vivono dentro ogni app e viaggiano con lei. Qui si decide cosa la piattaforma fa da sola, dove manda gli avvisi, a partire da quali valori si preoccupa, e quanto dura una sessione.

Si aprono dalla voce Impostazioni, in fondo alla barra laterale. Ci entrano solo gli account con profilo di amministratore.

Le sezioni sono in una navigazione a sinistra, per gruppi: Piattaforma, Avvisi, Osservabilità, Intelligenza artificiale, App, Installazione e Informazioni. Si apre una sezione alla volta, e l'indirizzo cambia con essa, quindi il pulsante indietro del browser porta alla sezione precedente. Il gruppo Installazione appare solo in un'installazione di una sola organizzazione. Su uno schermo stretto, la navigazione diventa un elenco a discesa sopra la sezione.

La schermata delle Impostazioni della piattaforma, con la navigazione delle sezioni a sinistra
La schermata delle Impostazioni della piattaforma, con la navigazione delle sezioni a sinistra

Nota

Ogni sezione ha il suo pulsante Salva, nell'intestazione, e salva solo quella sezione. Cambiare sezione senza salvare perde quello che vi era scritto.

Processi

La sezione Processi accende e spegne ciò che gira da solo mentre nessuno guarda. Sono tre interruttori indipendenti:

Interruttore Cosa succede quando è acceso Cosa si perde quando lo spegni
Pianificatore Esegue le pianificazioni, i report pianificati e i timer dei workflow. Niente viene eliminato: gli orari previsti semplicemente non partono finché non lo riaccendi.
Indice di osservabilità Porta ciò che le app registrano nell'indice centrale e applica i periodi di conservazione di ogni app. Le schermate del Radar mostrano dati vecchi e i record restano salvati per sempre.
Notifiche in tempo reale Le notifiche arrivano sulla schermata di chi sta lavorando, sul momento. Le notifiche continuano a essere create e consegnate — ma compaiono solo alla visita successiva.

L'interruttore degli avvisi via email è nella sezione Allarmi.

Ogni interruttore ha effetto quando clicchi su Salva, senza riavviare il server: ciò che attivi parte in quel momento, e le notifiche in tempo reale disattivate si chiudono subito.

I tre interruttori della sezione Processi
I tre interruttori della sezione Processi

Attenzione

Spegnere il Pianificatore è la causa numero uno di "i miei script hanno smesso di girare". Se una pianificazione sembra morta, controlla questo interruttore prima di indagare sullo script. Vale lo stesso per i report pianificati e per i passaggi di attesa nei workflow — dipendono tutti dallo stesso motore.

Antivirus

La sezione Antivirus collega la piattaforma a un antivirus tramite ICAP, perché i file che entrano nelle app vengano controllati prima di essere salvati, e mostra i file in quarantena. È spiegata in Antivirus.

Email

È da qui che la piattaforma manda gli allarmi suoi — da non confondere con l'email che ogni app manda ai propri utenti, che si configura nei canali di notifica dell'app.

Compila:

  1. Server e Porta del servizio email.
  2. Sicurezza — SSL/TLS cifra dall'inizio della connessione (porta 465); STARTTLS se il server lo offre apre la connessione senza cifratura e passa a TLS se il server lo offre (porta 587); Nessuna non cifra mai, per server interni senza TLS (porta 25). Senza utente né password, l'invio non si autentica.
  3. Utente e Password dell'account di invio. La password si scrive una volta e non torna mai sulla schermata: il campo passa a dire che è impostata, e lasciarlo vuoto significa "non toccare", mai "cancellare".
  4. Mittente — l'indirizzo che appare a chi riceve.
  5. Destinatari: indirizzi, separati da virgola, che ricevono tutti gli allarmi. In bianco, ogni app avvisa le persone assegnate, e le app senza nessuno assegnato e la piattaforma avvisano gli amministratori attivi.

La sezione dell'email degli avvisi compilata
La sezione dell'email degli avvisi compilata

Allarmi

La sezione Allarmi dice se la piattaforma avvisa via email e a partire da quali valori.

L'interruttore Avvisi via email, in alto, accende gli avvisi. Spento, nessuno viene avvisato, e i problemi si scoprono solo aprendo il Radar. Gli avvisi partono dal server della sezione Email.

Un nuovo problema in un'app pubblicata, o un problema risolto che si ripresenta, avvisa sempre, senza soglia. Cosa genera ogni avviso e cosa dice l'email è in Avvisi via email.

Le Soglie dicono alla piattaforma cosa è normale e cosa merita un'email. Tutte vengono valutate dentro la finestra definita alla fine della sezione.

Valore Cosa significa
Errori del server nelle API (%) Percentuale di richieste che falliscono sul server (5xx) oltre la quale si apre un allarme di errore generalizzato, con almeno 5 errori nella finestra. I rifiuti, le richieste annullate e gli errori di validazione non contano.
Richieste minime Sotto questo numero di richieste, la percentuale non conta. Un errore su tre richieste è il 33% e non vuol dire niente.
Script falliti Quante esecuzioni fallite aprono un allarme.
Ritardo della coda (s) Quanto tempo il lavoro in background può restare indietro prima di essere considerato in ritardo.
Disco libero (%) Sotto questa percentuale, avvisa.
Finestra (min) Il periodo su cui viene contato tutto quello che sta sopra.

Suggerimento

In un'installazione con poco traffico, alza le Richieste minime. È il campo che evita allarmi falsi nelle app che vengono usate solo la mattina.

Limiti

Due impostazioni che valgono per tutta la piattaforma:

  • Durata della sessione (h) — quanto dura una sessione senza attività. Mentre si lavora, la sessione si rinnova da sola; solo l'inattività prolungata obbliga a entrare di nuovo.
  • File massimo (MB) — la dimensione massima di un file caricato in qualunque app dell'installazione. Vale anche per i file caricati negli asset di un'app. Arriva fino a 100 MB. L'importazione di app non dipende da questo valore: accetta pacchetti fino a 1 GB (vedi Importare ed esportare app).

OpenTelemetry

La sezione OpenTelemetry, nel gruppo Osservabilità, invia ciò che succede nelle app al server OpenTelemetry dell'azienda, tramite OTLP su HTTP in JSON. Il Radar continua a funzionare come prima: l'invio è una copia.

  1. In Indirizzo, scrivi l'indirizzo base di OTLP su HTTP, per esempio https://otel.empresa.pt:4318. Keplin aggiunge /v1/traces e /v1/logs.
  2. Facoltativo: in Intestazioni, clicca su Aggiungi intestazione e scrivi il Nome e il Valore delle intestazioni di autenticazione del servizio, per esempio Authorization o x-api-key. I valori sono cifrati e non riappaiono; se vuoto, resta il valore salvato.
  3. In Cosa inviare, scegli:
    • Chiamate alle API ed esecuzioni di script, come trace, con gli id di trace e di span che Keplin usa già;
    • Errori del Radar, come log, con il tipo, il messaggio e lo stack dell'errore, collegati alla trace;
    • Audit, come log: chi ha cambiato cosa nella piattaforma, senza il prima e il dopo;
    • Attività nel browser, come trace: le schermate aperte, i clic e le letture. È tanta: attivala solo se il servizio la regge.
  4. Clicca su Prova connessione. La prova è superata quando il server accetta un invio di prova.
  5. Attiva Invia a OpenTelemetry e clicca su Salva.

La sezione OpenTelemetry, con l'indirizzo, un'intestazione e i segnali scelti
La sezione OpenTelemetry, con l'indirizzo, un'intestazione e i segnali scelti

L'invio inizia nel momento in cui si attiva, senza lo storico. I dati delle richieste e delle risposte non vengono mai inviati. Lo Stato mostra l'ora dell'ultimo invio e quanti span e log sono usciti dall'avvio del server, e l'ultimo errore, se è più recente dell'ultimo invio.

Indirizzo pubblico

L'Indirizzo pubblico è l'indirizzo da cui le persone aprono la piattaforma, per esempio https://piattaforma.esempio.it. È quello usato nei link delle email, come quello per recuperare la password degli account delle app. La sezione è nel gruppo Installazione, che compare solo in un'installazione con un solo tenant; in multitenant vale l'indirizzo di ogni tenant.

Viene compilato al primo accesso di un amministratore, con l'indirizzo da cui è entrato. Se non è l'indirizzo che le persone usano (per esempio, se l'amministratore è entrato dall'IP della rete interna), correggilo e fai clic su Salva.

Senza Indirizzo pubblico, il recupero della password funziona solo nelle app pubblicate su un dominio proprio. L'indirizzo che arriva con una richiesta non serve mai per il link, perché lo sceglie chi fa la richiesta.

Il server PostgreSQL della piattaforma

Per i datasource interni in PostgreSQL (vedi Collegare database), l'installazione ha bisogno di un server PostgreSQL dove la piattaforma crea i database. La configurazione è dell'installazione, non di un'app: in un'installazione per una sola organizzazione sta nelle Impostazioni, nella sezione PostgreSQL gestito del gruppo Installazione; in un'installazione con più clienti sta nel backoffice dell'installazione. Compila indirizzo, porta, account di amministrazione e limite di database per cliente, salva e usa Prova server per confermare che la piattaforma riesce a creare database su quel server. Finché non è configurato, l'opzione PostgreSQL della scheda Interno appare disattivata quando si crea un datasource.

Motore del browser

Gli screenshot che gli agenti chiedono tramite MCP e i test di schermata (vedi Il progetto di test) usano un browser senza schermo che gira sul server. Ce n'è uno solo per tutta l'installazione, in un processo a parte e con priorità bassa: quando la macchina è sotto pressione, a cedere è il browser, non le richieste delle app.

La sezione Motore del browser, nel gruppo Installazione (in un'installazione con più clienti, nel backoffice dell'installazione), mostra lo Stato (in esecuzione, o chiuso fino al prossimo lavoro), se Chromium è installato, i Lavori in esecuzione e in coda, la Memoria libera e l'Ultimo errore. E ha i limiti che proteggono il server:

Limite Cosa fa
Lavori contemporanei Quante pagine aperte allo stesso tempo. Più pagine, più memoria e CPU.
Richieste in coda Con la coda piena, una nuova richiesta viene rifiutata subito, con il motivo.
Minuti di inattività prima di chiudere Chiuso, il browser non occupa memoria; il lavoro successivo lo riapre.
Memoria libera minima (MB) Sotto questo valore non si apre nessuna nuova pagina. 0 disattiva la protezione.

Chiudi il browser ora restituisce subito la memoria. Se manca Chromium, Installa Chromium lo scarica; l'installazione e gli aggiornamenti della piattaforma lo installano già e verificano che si avvii.

Aggiornare la piattaforma

Dove e come si aggiorna dipende dalla modalità dell'installazione:

  • Installazione per una sola organizzazione: non c'è aggiornamento dall'interfaccia. La sezione Aggiornamenti delle Impostazioni mostra la Versione installata: e il comando da eseguire nella console del server con lo zip della versione nuova, con un pulsante per copiarlo. L'installatore conserva le impostazioni e i dati ed esegue le migrazioni; per tornare a una versione precedente si installa lo zip di quella versione.
  • Installazione con più clienti: l'aggiornamento si fa nel backoffice dell'installazione, in Aggiornamenti, ed è quella schermata che il resto di questa sezione descrive. Le Impostazioni di ogni cliente non hanno aggiornamenti.

La sezione di aggiornamento mostra la versione installata e l'elenco delle versioni disponibili. Il processo ha due pulsanti, di proposito:

  1. Prepara — va a prendere la versione scelta e la prepara senza toccare nulla di quello che sta servendo. La piattaforma continua a funzionare.
  2. Quando la preparazione termina, compare il piano: quanti database verranno migrati, quali file di app vengono riscritti e in quante versioni, più l'avviso che i database vengono copiati prima di toccare qualsiasi cosa.
  3. Applica questo aggiornamento — solo dopo aver letto il piano. La piattaforma resta indisponibile durante il riavvio e torna nella versione nuova.

Il piano di un aggiornamento, prima di essere applicato
Il piano di un aggiornamento, prima di essere applicato

Nota

Se un'app ha su disco modifiche che non sono ancora nella cronologia, il piano lo dice e l'aggiornamento le salva prima, in una voce a parte, prima di riscrivere i file. I file che la piattaforma scrive da sola, come le copie delle dipendenze degli script create da una pianificazione, non contano.

Se qualcosa va storto a metà, la versione precedente viene ripristinata automaticamente e la schermata lo dice — compreso il registro di quello che è fallito.

Il ripristino riporta allo stato precedente all'aggiornamento i database e anche i file delle app che le migrazioni avevano riscritto.

Verifica del server

Nella schermata degli aggiornamenti, il blocco Verifica del server mostra se la macchina ha ciò di cui hanno bisogno gli script delle app, le catture di schermata e i test di schermata: Chromium, l'isolamento degli script, le regole di rete degli script e i processi della piattaforma in esecuzione con l'utente dell'installazione. La verifica viene eseguita alla fine dell'installazione, alla fine di ogni aggiornamento e all'avvio del server; Verifica ora la esegue su richiesta.

Il riepilogo dice «È tutto a posto.», quanti avvisi ci sono, o quanti problemi restano da risolvere. Ogni problema dice cosa non funziona e mostra il comando che lo risolve, da eseguire come root nella console del server.

Intelligenza artificiale

Il gruppo Intelligenza artificiale contiene la sezione Fornitori: i servizi di IA del tenant che gli script delle app possono usare, con le credenziali e i modelli autorizzati. Vedi Fornitori di IA.

Autenticazione delle app

La sezione Autenticazione delle app, nel gruppo App, registra i fornitori tramite cui gli utenti delle app possono accedere: Microsoft Entra ID, Google, un servizio OpenID Connect o OAuth 2.0 e, in un'installazione con un solo tenant, Active Directory. È spiegata in Accedere con i fornitori di autenticazione.

App mobile

La sezione App mobile riguarda l'app Android con cui si entra nelle app di questa piattaforma. Ha due file da scaricare e un codice QR per app — è spiegata in dettaglio nel capitolo App mobile.

La sezione dell'app mobile, con i download e il codice QR
La sezione dell'app mobile, con i download e il codice QR

Modelli

La sezione Modelli, nel gruppo App, elenca i modelli di questa piattaforma: quelli salvati nelle app con Salva come modello (vedi Modelli di app). I modelli di sistema sono dell'installazione e non appaiono qui.

Ogni riga mostra il nome, la versione, la descrizione, l'app da cui proviene, la data in cui è stato salvato e la dimensione. Su ognuno:

  • Scarica trasferisce il file .keplintemplate, per portarlo in un'altra installazione.
  • L'icona del cestino elimina il modello. La conferma appare nella riga stessa: clicca su Elimina per confermare, o su Annulla. Il modello esce dalla galleria di Nuova app, e le app già create da esso non cambiano.

La sezione Modelli, con un modello salvato a partire da un'app
La sezione Modelli, con un modello salvato a partire da un'app

File inutilizzati

I file caricati nelle app non si eliminano da soli: né quando si elimina il record che li aveva, né quando si sostituisce un allegato, né quando un modulo resta a metà. La sezione File inutilizzati li trova e permette di scegliere cosa esce. Niente viene eliminato da solo.

  1. Clicca su Cerca file inutilizzati, nell'intestazione. La ricerca viene eseguita in background sul server: puoi uscire dalla pagina e tornare, e continua.
  2. Mentre cerca, la pagina mostra l'avanzamento (per esempio, «3 di 12 app») e cosa sta leggendo. Ogni app appare appena finisce, con i file che nessun riferimento conosciuto usa: nome, dimensione, data di caricamento e versioni. L'icona accanto al nome scarica il file, per verificare cos'è.
  3. Scegli i file e clicca su Elimina selezionati. La pagina chiede conferma; prima di eliminare, la piattaforma verifica di nuovo i file scelti, e un file che nel frattempo è passato a essere usato resta.

La sezione File inutilizzati, con il risultato dell'ultima ricerca
La sezione File inutilizzati, con il risultato dell'ultima ricerca

Il risultato resta salvato: tornando alla sezione, appare l'ultima ricerca, con la data e quanto è durata. Cerca di nuovo ripete la ricerca in tutte le app, e Cerca in questa app, nell'intestazione di un'app, solo in quella. Annulla la ricerca ferma una ricerca in corso. Se il server si riavvia a metà, la pagina dice che l'ultima ricerca è rimasta a metà. Tempo di ogni fonte mostra quanto ha impiegato ogni database letto, per capire dov'è il tempo di una ricerca lenta.

Un file conta come usato quando il suo token appare nella progettazione dell'app, nei database SQLite dell'app (compresi processi e notifiche) o in una colonna di testo di una tabella del modello, in qualsiasi versione. I datasource in sola lettura non si leggono, perché Keplin non ci scrive mai. Una tabella fuori dal modello o un sistema esterno non vengono visti: verifica prima di eliminare. I file delle ultime 24 ore non entrano, e un'app con un database che non si riesce a leggere resta fuori dall'elenco.

Attenzione

Un file eliminato non torna. I byte escono dall'archiviazione dell'app e il file esce dal registro di tutte le versioni.

Open source

La sezione Open source elenca le librerie open source installate nella piattaforma, con la versione e la licenza di ognuna. Il nome di ogni libreria apre la pagina del progetto. Scrivi nel campo di ricerca per filtrare l'elenco per nome o per licenza.

Domande frequenti

Ho cambiato una soglia e non ho ricevuto niente. Gli allarmi vengono valutati solo di minuto in minuto e soltanto dentro la finestra definita. Controlla anche che l'interruttore Avvisi via email, nella sezione Allarmi, sia acceso, e che il server della sezione Email sia compilato.

Posso avere server email diversi per app? Sì — ed è la norma. L'email di questa pagina è solo quella degli avvisi della piattaforma; ogni app configura i suoi canali nelle proprie impostazioni.

Chi riesce a vedere questa pagina? Solo gli account con profilo di amministratore. Un developer non la vede nella barra laterale né ci entra per indirizzo diretto.