docs: aggiungi README, PRD, progress e .gitignore con esclusione segreti

2026-04-24 13:06:36 +02:00
parent 29078c9db6
commit 96441e5e10
4 changed files with 769 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Supabase Pinger
+
+Tool Python dockerizzato pensato per mantenere "attivo" un database Supabase in free tier, evitando che venga spento e parcheggiato per inattivita'.
+
+L'idea e' semplice: il container resta in esecuzione fino a quando non viene fermato esplicitamente e, a intervalli regolari, esegue un'operazione verso il database Supabase per generare attivita' sufficiente a non far decadere l'istanza.
+
+## Obiettivo
+
+I progetti Supabase in free tier possono diventare temporaneamente inaccessibili se rimangono inattivi troppo a lungo. Questo progetto serve a:
+
+- mantenere raggiungibile il database nel tempo;
+- centralizzare la configurazione in un file `.env`;
+- fornire anche un file `.env.example` come modello;
+- girare in un container Docker sempre attivo, finche' non viene arrestato manualmente.
+
+## Come funziona
+
+Il servizio viene eseguito all'interno di un container Docker e resta attivo in modo continuativo. A ogni ciclo:
+
+1. legge la configurazione dal file `.env`;
+2. apre una connessione al database Supabase/PostgreSQL;
+3. esegue una query o un'operazione leggera di keep-alive;
+4. attende l'intervallo configurato;
+5. ripete il processo fino allo stop del container.
+
+## Configurazione
+
+La configurazione deve essere persistita in un file `.env`, non hardcoded nel codice o nel Dockerfile.
+
+E' consigliato mantenere nel repository anche un file `.env.example` con le sole chiavi, senza valori reali, per documentare le variabili richieste.
+
+### Esempio di `.env.example`
+
+```env
+SUPABASE_DB_HOST=
+SUPABASE_DB_PORT=5432
+SUPABASE_DB_NAME=
+SUPABASE_DB_USER=
+SUPABASE_DB_PASSWORD=
+PING_INTERVAL_MINUTES=30
+PING_QUERY=SELECT 1;
+TZ=Europe/Rome
+```
+
+### Significato delle variabili
+
+- `SUPABASE_DB_HOST`: hostname del database Supabase.
+- `SUPABASE_DB_PORT`: porta del database PostgreSQL, normalmente `5432`.
+- `SUPABASE_DB_NAME`: nome del database.
+- `SUPABASE_DB_USER`: utente di connessione.
+- `SUPABASE_DB_PASSWORD`: password di connessione.
+- `PING_INTERVAL_MINUTES`: intervallo tra un keep-alive e il successivo.
+- `PING_QUERY`: query leggera da eseguire per generare attivita'.
+- `TZ`: timezone del container per logging e scheduling coerenti.
+
+## Docker
+
+Il container deve rimanere in esecuzione continua. In pratica, il processo Python non deve terminare dopo il primo ping, ma restare in loop fino a interruzione esplicita.
+
+### Build
+
+```bash
+docker build -t supabase-pinger .
+```
+
+### Avvio con file `.env`
+
+```bash
+docker run -d \
+  --name supabase-pinger \
+  --env-file .env \
+  --restart unless-stopped \
+  supabase-pinger
+```
+
+L'opzione `--restart unless-stopped` e' la piu' adatta a questo caso: il container viene mantenuto attivo e riparte automaticamente dopo reboot o crash, ma si ferma se viene arrestato intenzionalmente.
+
+### Arresto
+
+```bash
+docker stop supabase-pinger
+```
+
+## Esempio con Docker Compose
+
+```yaml
+services:
+  supabase-pinger:
+    build: .
+    container_name: supabase-pinger
+    env_file:
+      - .env
+    restart: unless-stopped
+```
+
+Avvio:
+
+```bash
+docker compose up -d
+```
+
+Stop:
+
+```bash
+docker compose down
+```
+
+## Struttura minima attesa del progetto
+
+```text
+.
+|-- .env
+|-- .env.example
+|-- Dockerfile
+|-- requirements.txt
+|-- app.py
+`-- README.md
+```
+
+## Note operative
+
+- Non committare mai il file `.env` con credenziali reali.
+- Committa solo `.env.example` con valori vuoti o fittizi.
+- Usa query di keep-alive molto leggere, ad esempio `SELECT 1;`.
+- Mantieni intervalli ragionevoli: troppo frequenti sono inutili, troppo lunghi rischiano di non prevenire il parcheggio del database.
+- Se il progetto viene eseguito su un host sempre acceso, Docker con policy `unless-stopped` e' sufficiente per il requisito di esecuzione continua.
+
+## Scopo del repository
+
+Questo repository ospita un servizio minimale e operativo, pensato per un solo compito: impedire che un database Supabase free tier diventi temporaneamente non disponibile per inattivita'.