Luca Sacchi Ricciardi
135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
# 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=db.<project-ref>.supabase.co
|
|
SUPABASE_DB_PORT=5432
|
|
SUPABASE_DB_NAME=postgres
|
|
SUPABASE_DB_USER=postgres
|
|
SUPABASE_DB_PASSWORD=
|
|
PING_INTERVAL_MINUTES=4320
|
|
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. Default `4320` (72 ore, circa 3 volte a settimana).
|
|
- `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 del progetto
|
|
|
|
```text
|
|
.
|
|
|-- .env # credenziali locali (non versionato)
|
|
|-- .env.example # modello variabili senza segreti
|
|
|-- .gitignore
|
|
|-- app.py # entrypoint del servizio
|
|
|-- docker-compose.yml
|
|
|-- Dockerfile
|
|
|-- prd.md # product requirements document
|
|
|-- progress.md # piano e stato di sviluppo
|
|
|-- README.md
|
|
`-- requirements.txt
|
|
```
|
|
|
|
## 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'.
|