docs: aggiungi README, PRD, progress e .gitignore con esclusione segreti
This commit is contained in:
Luca Sacchi Ricciardi
@@ -0,0 +1,340 @@
|
||||
# PRD: Supabase Auto-Shutdown Prevention System
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
Questo progetto definisce un servizio Python dockerizzato con il solo scopo di mantenere attivo un database Supabase in free tier, prevenendo la sospensione automatica dovuta a lunghi periodi di inattivita'.
|
||||
|
||||
La soluzione prevista e' un processo long-running eseguito in un container Docker che:
|
||||
|
||||
- carica la configurazione da file `.env`;
|
||||
- si connette al database Supabase/PostgreSQL;
|
||||
- esegue periodicamente una query leggera di keep-alive;
|
||||
- registra esito e tempi di esecuzione;
|
||||
- continua a funzionare finche' il container non viene fermato.
|
||||
|
||||
## 2. Problema
|
||||
|
||||
Nel piano gratuito di Supabase, un progetto puo' essere sospeso o parcheggiato dopo un periodo prolungato di inattivita'. Quando questo avviene:
|
||||
|
||||
- il database puo' diventare temporaneamente non raggiungibile;
|
||||
- l'applicazione che lo usa puo' apparire guasta o lenta al primo accesso;
|
||||
- l'esperienza di sviluppo, demo o staging peggiora sensibilmente.
|
||||
|
||||
Il problema da risolvere non e' l'alta disponibilita' in senso enterprise, ma la continuita' operativa minima per ambienti personali, prototipi, demo e staging leggeri.
|
||||
|
||||
## 3. Obiettivo di Prodotto
|
||||
|
||||
Garantire che Supabase rilevi attivita' reale sul database almeno una volta entro ogni finestra di 7 giorni, con un margine di sicurezza sufficiente a evitare la sospensione automatica nella pratica.
|
||||
|
||||
## 4. Obiettivi Specifici
|
||||
|
||||
- Eseguire automaticamente attivita' valida sul database senza intervento umano.
|
||||
- Mantenere il processo attivo in modo continuativo tramite container Docker.
|
||||
- Consentire configurazione interamente tramite `.env`.
|
||||
- Rendere il comportamento osservabile con log chiari di successo e fallimento.
|
||||
- Mantenere la soluzione minimale, portabile e facile da eseguire su qualsiasi host con Docker.
|
||||
|
||||
## 5. Non-Obiettivi
|
||||
|
||||
- Non e' un sistema di backup, replica o disaster recovery.
|
||||
- Non e' un sistema di monitoraggio completo del database.
|
||||
- Non deve gestire provisioning, creazione schema o migrazioni Supabase.
|
||||
- Non deve introdurre traffico aggressivo o pattern assimilabili ad abuso del free tier.
|
||||
- Non deve dipendere obbligatoriamente da GitHub Actions, servizi cron esterni o infrastrutture cloud aggiuntive.
|
||||
|
||||
## 6. Pubblico di Riferimento
|
||||
|
||||
- Sviluppatori individuali che usano Supabase free tier per prototipi.
|
||||
- Team piccoli che usano Supabase come ambiente di staging leggero.
|
||||
- Progetti personali o dimostrativi che devono restare pronti all'uso senza accessi frequenti.
|
||||
|
||||
## 7. User Stories
|
||||
|
||||
- Come sviluppatore, voglio che il mio database Supabase resti raggiungibile anche se non uso l'app per giorni.
|
||||
- Come maintainer, voglio configurare il servizio con un semplice file `.env` senza modificare il codice.
|
||||
- Come operatore, voglio eseguire il servizio in Docker e lasciarlo attivo finche' non decido di fermarlo.
|
||||
- Come utente tecnico, voglio vedere nei log se il keep-alive sta funzionando oppure no.
|
||||
|
||||
## 8. Scope della Soluzione
|
||||
|
||||
La soluzione target per questo repository e':
|
||||
|
||||
- applicazione Python;
|
||||
- esecuzione in container Docker;
|
||||
- loop applicativo continuo;
|
||||
- connessione diretta a PostgreSQL/Supabase;
|
||||
- query di keep-alive configurabile;
|
||||
- configurazione tramite file `.env` e `.env.example`.
|
||||
|
||||
Alternative come GitHub Actions, `pg_cron` o cron esterni restano opzioni comparabili, ma non rappresentano la soluzione primaria di questo repository.
|
||||
|
||||
## 9. Assunzioni di Prodotto
|
||||
|
||||
- Supabase considera una query SQL valida come attivita' sufficiente a evitare la sospensione per inattivita'.
|
||||
- Un'attivita' 2 o 3 volte a settimana offre margine adeguato rispetto alla finestra di 7 giorni.
|
||||
- L'host che esegue Docker resta normalmente acceso o comunque ripristina il container tramite restart policy.
|
||||
- L'utente dispone delle credenziali di accesso al database Supabase.
|
||||
|
||||
## 10. Requisiti Funzionali
|
||||
|
||||
### RF1. Caricamento configurazione da `.env`
|
||||
|
||||
Il sistema deve caricare tutti i parametri necessari da file `.env`.
|
||||
|
||||
Parametri minimi richiesti:
|
||||
|
||||
- `SUPABASE_DB_HOST`
|
||||
- `SUPABASE_DB_PORT`
|
||||
- `SUPABASE_DB_NAME`
|
||||
- `SUPABASE_DB_USER`
|
||||
- `SUPABASE_DB_PASSWORD`
|
||||
- `PING_INTERVAL_MINUTES`
|
||||
- `PING_QUERY`
|
||||
- `TZ`
|
||||
|
||||
### RF2. Presenza di `.env.example`
|
||||
|
||||
Il repository deve includere un file `.env.example` che documenti tutte le variabili necessarie senza contenere segreti reali.
|
||||
|
||||
### RF3. Connessione al database Supabase
|
||||
|
||||
Il sistema deve aprire una connessione verso il database PostgreSQL di Supabase usando le credenziali fornite.
|
||||
|
||||
### RF4. Esecuzione di attivita' reale
|
||||
|
||||
Il sistema deve eseguire un'operazione SQL reale che venga contabilizzata come attivita' dal database.
|
||||
|
||||
Comportamento previsto:
|
||||
|
||||
- default consigliato: query leggera come `SELECT 1;`;
|
||||
- opzione futura: query custom o update su tabella tecnica di log;
|
||||
- l'operazione deve essere configurabile tramite environment variable.
|
||||
|
||||
### RF5. Esecuzione periodica automatizzata
|
||||
|
||||
Il processo deve essere automatico e ciclico, senza intervento umano manuale dopo l'avvio del container.
|
||||
|
||||
Vincoli di frequenza:
|
||||
|
||||
- il sistema deve supportare un intervallo configurabile;
|
||||
- l'intervallo operativo raccomandato deve garantire almeno 2 esecuzioni a settimana;
|
||||
- il default di prodotto consigliato e' tra 72 e 96 ore;
|
||||
- non devono essere usati intervalli inutilmente aggressivi come default.
|
||||
|
||||
### RF6. Processo long-running
|
||||
|
||||
Il processo Python non deve terminare dopo un singolo ping riuscito o fallito. Deve restare attivo e continuare a schedulare i cicli successivi finche' il container non viene fermato.
|
||||
|
||||
### RF7. Logging di esecuzione
|
||||
|
||||
Il sistema deve emettere log almeno per:
|
||||
|
||||
- avvio del servizio;
|
||||
- lettura configurazione valida;
|
||||
- tentativo di connessione;
|
||||
- esecuzione query;
|
||||
- successo dell'operazione;
|
||||
- errore dell'operazione;
|
||||
- attesa del prossimo ciclo.
|
||||
|
||||
### RF8. Gestione errori resiliente
|
||||
|
||||
In caso di fallimento di connessione o query, il processo non deve terminare immediatamente. Deve:
|
||||
|
||||
- loggare l'errore;
|
||||
- chiudere in sicurezza eventuali risorse aperte;
|
||||
- attendere il prossimo intervallo o un retry definito;
|
||||
- riprovare automaticamente.
|
||||
|
||||
### RF9. Arresto controllato
|
||||
|
||||
Il processo deve supportare lo stop del container in modo ordinato, chiudendo connessioni e terminando il loop senza lasciare risorse sporche.
|
||||
|
||||
### RF10. Modalita' di esecuzione containerizzata
|
||||
|
||||
Il sistema deve essere eseguibile tramite Docker con restart policy adatta a mantenerlo operativo finche' non viene fermato esplicitamente.
|
||||
|
||||
Policy target:
|
||||
|
||||
- `unless-stopped` come impostazione raccomandata.
|
||||
|
||||
### RF11. Notifica di errore opzionale
|
||||
|
||||
La notifica all'utente in caso di fallimento e' opzionale in prima versione.
|
||||
|
||||
Per la V1, il requisito minimo e' il logging locale/STDOUT. In versioni successive, potranno essere introdotte integrazioni opzionali come email, webhook o Telegram.
|
||||
|
||||
## 11. Requisiti Non Funzionali
|
||||
|
||||
### RNF1. Semplicita'
|
||||
|
||||
La soluzione deve restare piccola, leggibile e con poche dipendenze.
|
||||
|
||||
### RNF2. Portabilita'
|
||||
|
||||
Il servizio deve poter girare su qualsiasi ambiente che supporti Docker: VPS, mini PC, NAS, server domestico o macchina di sviluppo.
|
||||
|
||||
### RNF3. Sicurezza
|
||||
|
||||
- Nessun segreto hardcoded nel codice.
|
||||
- Nessun segreto committato nel repository.
|
||||
- Tutti i segreti devono essere passati tramite `.env` o strumenti equivalenti.
|
||||
|
||||
### RNF4. Osservabilita' minima
|
||||
|
||||
I log devono essere sufficienti a diagnosticare se il job di keep-alive ha funzionato senza richiedere debugging interattivo.
|
||||
|
||||
### RNF5. Basso impatto
|
||||
|
||||
Il sistema deve usare query leggere e frequenza moderata per minimizzare costo computazionale e rischio di comportamento eccessivo verso il free tier.
|
||||
|
||||
## 12. Configurazione di Prodotto
|
||||
|
||||
### Variabili richieste
|
||||
|
||||
```env
|
||||
SUPABASE_DB_HOST=
|
||||
SUPABASE_DB_PORT=5432
|
||||
SUPABASE_DB_NAME=
|
||||
SUPABASE_DB_USER=
|
||||
SUPABASE_DB_PASSWORD=
|
||||
PING_INTERVAL_MINUTES=4320
|
||||
PING_QUERY=SELECT 1;
|
||||
TZ=Europe/Rome
|
||||
```
|
||||
|
||||
### Note sulla configurazione
|
||||
|
||||
- `PING_INTERVAL_MINUTES=4320` equivale a 72 ore.
|
||||
- Il valore effettivo puo' essere modificato, ma il default raccomandato deve restare prudente rispetto ai termini d'uso e al limite dei 7 giorni.
|
||||
- Il file `.env.example` deve contenere le stesse chiavi, ma senza valori sensibili.
|
||||
|
||||
## 13. Flusso Operativo Atteso
|
||||
|
||||
1. L'utente crea il file `.env` partendo da `.env.example`.
|
||||
2. L'utente avvia il container con `--env-file .env`.
|
||||
3. Il processo Python parte e valida la configurazione.
|
||||
4. Il servizio apre una connessione al database Supabase.
|
||||
5. Il servizio esegue la query di keep-alive.
|
||||
6. Il servizio registra esito e timestamp.
|
||||
7. Il servizio attende fino al ciclo successivo.
|
||||
8. Il loop continua finche' il container non viene fermato.
|
||||
|
||||
## 14. Architettura Logica
|
||||
|
||||
Componenti logici previsti:
|
||||
|
||||
- loader configurazione: valida e carica le variabili ambiente;
|
||||
- scheduler loop: gestisce l'attesa fra i cicli;
|
||||
- database client: apre connessione ed esegue la query;
|
||||
- logger: stampa esiti ed errori su STDOUT/STDERR;
|
||||
- runtime Docker: mantiene il processo eseguito come container persistente.
|
||||
|
||||
## 15. Soluzioni Tecniche Valutate
|
||||
|
||||
| Soluzione | Descrizione | Pro | Contro | Esito |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Python + Docker long-running | Processo residente che esegue query periodiche via connessione DB diretta. | Indipendente da servizi terzi, semplice da portare ovunque, coerente con il repository. | Richiede un host sempre acceso. | Scelta primaria |
|
||||
| GitHub Actions | Workflow schedulato con chiamata HTTP o query indiretta. | Facile da configurare, economico. | Dipende da GitHub e da scheduling esterno. | Alternativa |
|
||||
| pg_cron | Job schedulati internamente al database. | Soluzione interna a Postgres. | Affidabilita' e disponibilita' non sempre ideali su free tier. | Non primaria |
|
||||
| External Cron | Servizi terzi che attivano un endpoint o una function. | Molto affidabile. | Dipendenza esterna aggiuntiva. | Alternativa |
|
||||
|
||||
## 16. Vincoli e Rischi
|
||||
|
||||
### Vincoli
|
||||
|
||||
- Uso del piano gratuito Supabase.
|
||||
- Necessita' di rispettare termini e limiti del servizio.
|
||||
- Presenza di un host Docker sempre disponibile o quasi sempre disponibile.
|
||||
|
||||
### Rischi
|
||||
|
||||
- Una frequenza troppo alta potrebbe essere interpretata come utilizzo artificiale o eccessivo.
|
||||
- Una frequenza troppo bassa potrebbe non prevenire il parking.
|
||||
- Credenziali esposte in repository o log rappresentano rischio di sicurezza.
|
||||
- Cambiamenti futuri nelle policy Supabase potrebbero ridurre l'efficacia della soluzione.
|
||||
|
||||
### Mitigazioni
|
||||
|
||||
- Default conservativo a poche esecuzioni settimanali.
|
||||
- Query molto leggere.
|
||||
- Segreti solo in `.env`.
|
||||
- Logging senza stampa delle credenziali.
|
||||
|
||||
## 17. Requisiti di Sicurezza
|
||||
|
||||
- Il sistema non deve stampare password o DSN completi nei log.
|
||||
- Il file `.env` deve essere escluso dal versionamento.
|
||||
- Il file `.env.example` deve essere versionato come riferimento.
|
||||
- Eventuali errori devono essere sanitizzati per evitare leak accidentali di segreti.
|
||||
|
||||
## 18. Requisiti di Deployment
|
||||
|
||||
- Il progetto deve essere buildabile tramite `docker build`.
|
||||
- Il progetto deve poter essere eseguito con `docker run --env-file .env`.
|
||||
- Deve essere compatibile anche con `docker compose`.
|
||||
- La restart policy raccomandata deve essere `unless-stopped`.
|
||||
|
||||
## 19. Metriche di Successo
|
||||
|
||||
- Il database Supabase non entra in stato paused durante normali periodi di mancato utilizzo dell'applicazione.
|
||||
- Ogni esecuzione pianificata produce un log di successo oppure un log di errore esplicito.
|
||||
- Il container resta in esecuzione senza terminare dopo il primo ciclo.
|
||||
- La configurazione puo' essere modificata senza cambiare il codice applicativo.
|
||||
|
||||
## 20. Acceptance Criteria
|
||||
|
||||
### AC1. Configurazione
|
||||
|
||||
- Esiste un file `.env.example` completo con tutte le variabili richieste.
|
||||
- Il servizio fallisce in modo chiaro se manca una variabile obbligatoria.
|
||||
|
||||
### AC2. Keep-alive riuscito
|
||||
|
||||
- A container avviato, il servizio esegue con successo almeno una query di keep-alive verso Supabase.
|
||||
- I log mostrano chiaramente l'avvenuta esecuzione con timestamp.
|
||||
|
||||
### AC3. Continuita' del processo
|
||||
|
||||
- Dopo una query riuscita, il processo non termina.
|
||||
- Il container rimane in stato attivo fino a stop manuale o errore esterno del runtime.
|
||||
|
||||
### AC4. Tolleranza ai fallimenti
|
||||
|
||||
- Se una query fallisce, il processo logga l'errore e continua a riprovare nei cicli successivi.
|
||||
|
||||
### AC5. Sicurezza di configurazione
|
||||
|
||||
- Nessuna credenziale reale compare nel repository tracciato.
|
||||
- Le istruzioni d'uso spiegano chiaramente la differenza tra `.env` e `.env.example`.
|
||||
|
||||
### AC6. Coerenza con il free tier
|
||||
|
||||
- Il sistema consente una schedulazione moderata, raccomandata su 2-3 esecuzioni a settimana.
|
||||
|
||||
## 21. Roadmap Evolutiva
|
||||
|
||||
### V1
|
||||
|
||||
- Connessione diretta al database.
|
||||
- Query di keep-alive configurabile.
|
||||
- Loop continuo.
|
||||
- Logging base.
|
||||
- Container Docker con restart policy consigliata.
|
||||
|
||||
### V1.1
|
||||
|
||||
- Retry con backoff configurabile.
|
||||
- Miglioramento dei messaggi di health e startup.
|
||||
- Distinzione chiara tra errori di configurazione e di rete.
|
||||
|
||||
### V2
|
||||
|
||||
- Notifiche opzionali su webhook o email.
|
||||
- Healthcheck Docker dedicato.
|
||||
- Modalita' dry-run o startup check.
|
||||
- Supporto a metriche esportabili.
|
||||
|
||||
## 22. Decisione di Prodotto
|
||||
|
||||
La soluzione da implementare in questo repository e' un servizio Python sempre attivo, eseguito in Docker, configurato via `.env`, con query di keep-alive leggera e frequenza moderata. Questa scelta massimizza semplicita', portabilita' e controllo operativo, riducendo dipendenze esterne rispetto alle alternative basate su scheduler di terze parti.
|
||||
Reference in New Issue
Block a user