Supabase self-hosted su VPS con Docker
Avvia lo stack Docker ufficiale di Supabase sul tuo server: sostituisci i secret dimostrativi, gestisci 11 servizi, RAM, backup e aggiornamenti senza perdere il database.
Cosa stai creando
Self-hosting Supabase significa eseguire sul proprio server lo stack Docker Compose ufficiale: Postgres, un'API REST che vi si collega, un servizio di autenticazione, l'archiviazione dei file, i WebSocket realtime e la dashboard Studio. Si clona un repository, si modifica un unico file .env e si avviano undici container che, insieme, si comportano come un progetto Supabase sotto il proprio controllo.
L'installazione è breve. Il problema principale riguarda il file .env. Contiene secret dimostrativi pubblicati nel repository; uno stack avviato con questi valori predefiniti è accessibile a chiunque li individui. Questa guida illustra quali secret sostituire, a cosa serve ogni servizio, quanta memoria richiede realmente lo stack e come aggiornarlo senza eliminare il database.
Se Compose è una novità, leggere prima Nozioni di base su Docker Compose su un VPS. Tutto ciò che segue presuppone che docker compose version restituisca già una versione.
Cosa contiene realmente lo stack
Supabase non è un singolo programma. Il file Compose avvia un insieme di servizi separati sulla stessa rete. Capire il ruolo di ciascuno consente di trasformare un lungo elenco di nomi di container in qualcosa che si può analizzare.
dbè PostgreSQL con le estensioni Supabase caricate. Tutti gli altri servizi comunicano con questo servizio. Se questo container non è integro, anche tutti gli altri servizi smettono di funzionare.api-gwè il gateway API. Dalla release di August 2026 esegue Envoy; prima era un servizio chiamatokong, mentre Kong è ancora disponibile come override opzionale. È in ascolto sulla porta 8000 e instrada/rest/v1/,/auth/v1/e/storage/v1/al backend corretto. È l'unico container che si dovrebbe esporre.restè PostgREST. Legge lo schema Postgres e lo espone come API REST. In questo modo una nuova tabella diventa un nuovo endpoint senza scrivere codice.authè GoTrue. Emette i JSON Web Token (JWT) che identificano gli utenti.storageeimgproxygestiscono i caricamenti dei file e il ridimensionamento delle immagini.realtimetrasmette le modifiche al database tramite WebSocket.studioemetasono la dashboard e l'API di amministrazione che la supporta.functionsè il runtime edge basato su Deno, mentresupavisorè il connection pooler di Postgres.
I log e le analisi (Logflare e vector) sono stati rimossi dal file Compose predefinito a June 2026. Ora sono disponibili in un file di override opzionale, che si abilita con sh run.sh config add logs, usando lo stesso livello di composizione descritto in eseguire uno stack usando più file Compose.
Questo elenco spiega i valori delle risorse riportati di seguito. Non si sta eseguendo un database. Si sta eseguendo un database più dieci servizi di supporto.
Dimensionamento: prevedere 8 GB di RAM
In un'installazione pulita, a luglio 2026, lo stack utilizzava da inattivo circa 2.5-3 GB di memoria residente, prima di aggiungere dati o traffico propri. In quella misurazione, il servizio analytics e il processo Node.js di Studio erano i due maggiori consumatori singoli. Analytics non fa più parte dello stack predefinito, quindi consuma memoria soltanto se si abilita l'override dei log. Un server con 2 GB avvia i container, dopodiché il kernel ne termina uno tramite l'out of memory killer. Il sintomo è un container bloccato in riavvio con codice di uscita 137. La documentazione ufficiale di Supabase per il self-hosting, verificata a ottobre 2026, indica come requisiti minimi 4 GB di RAM, 2 core CPU e 40 GB di SSD, mentre raccomanda 8 GB, 4 core e 80 GB.
Assegna 8 GB di RAM e 4 vCPU a qualsiasi ambiente da cui dipendono servizi importanti. 4 GB sono sufficienti per un'istanza di sviluppo individuale, se si accetta che una query pesante e una sessione Studio eseguite contemporaneamente siano lente. Anche il disco è importante, perché Postgres, il volume di storage e, se abiliti i log, i relativi dati risiedono tutti nella directory del progetto. Inizia con 40 GB e monitora l'utilizzo. Contare i servizi prima di scegliere un piano è una buona abitudine per qualsiasi servizio self-hosted, perché anche PhotoPrism e Immich hanno requisiti minimi effettivi di RAM: la pagina quick start di Immich, verificata a ottobre 2026, richiede almeno 6 GB di RAM e 2 core CPU. Se per ora il progetto non necessita di un server così potente, confronta questa soluzione con ciò che include realmente il piano cloud gratuito di Supabase, perché una piccola applicazione che resta sotto 500 MB e non rimane inattiva per una settimana può essere eseguita senza costi.
Installazione: clonare il repository ufficiale
La procedura supportata copia la directory docker dal repository principale in una directory di progetto dedicata. Questa separazione è importante perché impedisce a un successivo git pull di sovrascrivere il tuo .env.
git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pulldocker compose pull scarica diversi gigabyte di immagini. Al termine, ogni servizio dovrebbe essere contrassegnato come Pulled. Un errore manifest unknown in questa fase indica che il tag dell’immagine bloccato è stato rimosso upstream. Per risolvere il problema, scarica una copia più recente del repository invece di modificare manualmente i tag.
I secret che devi modificare prima del primo avvio
Esegui questa operazione prima di avviare lo stack, non dopo. Al primo avvio, diversi valori vengono scritti nei dati persistenti. Modificarli in seguito richiede il ripristino del database.
Il repository include un generatore che produce correttamente tutti i valori, comprese le due chiavi API che devono essere firmate con il nuovo secret JWT.
sh utils/generate-keys.sh --update-envLo script scrive nuovi valori per JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, SECRET_KEY_BASE, REALTIME_DB_ENC_KEY, VAULT_ENC_KEY, PG_META_CRYPTO_KEY, i token Logflare, le chiavi del protocollo S3 e MINIO_ROOT_PASSWORD in .env. Da ottobre 2026 scrive anche valori casuali per POSTGRES_PASSWORD e DASHBOARD_PASSWORD. Richiede openssl, presente in qualsiasi immagine Ubuntu standard. Poiché ora riscrive anche la password del database, eseguilo con --update-env solo prima del primo avvio, mai su uno stack che contiene già dati.
In .env è comunque consigliabile controllare manualmente due valori:
POSTGRES_PASSWORD. Lo script lo valorizza con caratteri esadecimali casuali, una scelta sicura. Se lo sostituisci con un valore personalizzato, usa solo lettere e cifre. La punteggiatura in questo valore interrompe le stringhe di connessione che diversi servizi costruiscono concatenando stringhe. L'errore appare come un errore di autenticazione, non di analisi sintattica, e porta a cercare la causa nel posto sbagliato.DASHBOARD_USERNAMEeDASHBOARD_PASSWORD. Sono le credenziali di autenticazione di base per Studio. Lo script imposta una password casuale, ma lascia il nome utente predefinitosupabase. La password predefinita inclusa è letteralmentethis_password_is_insecure_and_should_be_updated. Se non hai eseguito lo script, modificala ora.
È importante capire perché ANON_KEY e SERVICE_ROLE_KEY non possono essere inventate. Entrambe sono JWT firmate con JWT_SECRET. Il gateway accetta solo le chiavi esatte presenti in .env, mentre i servizi che si trovano dietro il gateway verificano la firma rispetto a JWT_SECRET. Una chiave non corrispondente viene quindi rifiutata con HTTP 401. Il gateway Envoy predefinito risponde con 401 Unauthorized. Lo stesso vale per l'override Kong attuale, che esegue Kong 3.9 e restituisce {"message":"Unauthorized"}. Le installazioni precedenti a marzo 2026 eseguivano Kong 2.8, che risponde con {"message":"Invalid authentication credentials"}. Questo è il problema più comune nelle installazioni self-hosted: l'operatore modifica JWT_SECRET, ma mantiene le chiavi di esempio. Genera sempre tutte e tre insieme.
Tratta SERVICE_ROLE_KEY come una password di root. Ignora completamente la sicurezza a livello di riga. Deve essere usato nel codice lato server e in nessun altro contesto.
Imposta SITE_URL sull'indirizzo della tua applicazione e API_EXTERNAL_URL sull'indirizzo pubblico dell'API, aggiungendo /auth/v1 alla fine, ad esempio https://supabase.example.com/auth/v1. Imposta SUPABASE_PUBLIC_URL sullo stesso indirizzo pubblico, senza il percorso. Auth costruisce i link di conferma dell'indirizzo email e i callback OAuth a partire da questi valori. Se lasci i valori localhost predefiniti, tutti gli utenti verranno reindirizzati al proprio computer.
Poi controlla i valori configurati:
sh run.sh secretsAvvialo e verifica che sia operativo
sh run.sh start
docker compose psrun.sh start esegue il wrapping di docker compose up -d --wait, quindi non restituisce il prompt finché i controlli di integrità non hanno esito positivo. Ogni servizio dovrebbe mostrare running (healthy) oppure running. Il primo avvio richiede da due a quattro minuti, perché Postgres esegue gli script di inizializzazione prima che qualsiasi altro componente possa connettersi.
Se un container viene riavviato, leggi i relativi log usando il nome del servizio:
docker compose logs db
docker compose logs authStudio è quindi disponibile sulla porta 8000 e chiederà il nome utente e la password della dashboard configurati.
Non esporre la porta 8000 a Internet
Il gateway sulla porta 8000 usa HTTP in chiaro. Ogni chiave API e ogni password utente attraversa la rete in testo in chiaro. Le credenziali di Studio usano l'autenticazione di base, che applica la codifica base64 e non la crittografia.
Configura un reverse proxy davanti al gateway e termina lì TLS (transport layer security). Associa quindi il gateway all'indirizzo di loopback, in modo che nessun altro possa raggiungerlo. In docker-compose.yml, la riga della porta sotto il servizio api-gw diventa 127.0.0.1:${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000/tcp, mentre il proxy inoltra le richieste a quella porta. In un'installazione precedente al passaggio a Envoy di agosto 2026, la stessa riga della porta si trova invece sotto un servizio chiamato kong. Traefik davanti a più applicazioni Compose descrive la configurazione dei certificati. Lo stesso proxy finirà per gestire anche tutti gli altri servizi sul server, da questo stack fino a qualcosa di poco serio come una libreria Jellyfin ricostruita come un videonoleggio degli anni 90, e ciascuno richiede un hostname invece di un'altra porta aperta. Se una dashboard è destinata esclusivamente al tuo utilizzo, puoi evitare il proxy e raggiungere la porta di loopback tramite un tunnel SSH. È lo stesso approccio usato da open-kritt self-hosted per mantenere completamente fuori da Internet l'interfaccia di scansione.
Chiudi anche il resto nel firewall, perché Docker pubblica le porte scrivendo regole iptables proprie, che una configurazione ingenua di ufw non intercetta. Questo problema è spiegato in perché i container Docker ignorano le regole ufw.
Eseguire il backup del database, non della directory
I dati di Postgres si trovano in un bind mount in ./volumes/db/data. Copiare quella directory mentre il container è in esecuzione produce una copia incoerente, perché Postgres memorizza in buffer le scritture e i file su disco sono coerenti solo al checkpoint. Il ripristino di questa copia in genere funziona, ma può anche perdere senza segnalarlo le transazioni più recenti. È il peggior tipo di errore possibile per un backup.
Eseguire invece un dump. pg_dumpall viene eseguito all'interno del container e produce uno snapshot coerente:
docker exec -t supabase-db pg_dumpall -U postgres > supabase-$(date +%F).sqlVerificare che il file non sia vuoto prima di considerarlo valido. Trasferire quindi periodicamente i dump fuori dal server, come previsto da backup cifrati fuori sede con restic. Un dump pianificato che termina senza segnalare l'errore equivale, di fatto, a nessun backup. Configurare quindi il job cron o systemd in modo che invii un avviso al telefono quando termina con un codice diverso da zero. Eseguire contemporaneamente il backup di .env. La perdita di JWT_SECRET rende non valido ogni token emesso e impedisce di leggere ogni secret cifrato memorizzato.
I file caricati si trovano in ./volumes/storage. Sono file ordinari, quindi è sufficiente una copia normale.
Aggiornare senza perdere dati
Supabase fissa le versioni delle immagini in docker-compose.yml, quindi nulla cambia finché non lo aggiorni esplicitamente. Conviene adottare lo stesso approccio in ogni stack assemblato manualmente. Per questo un relay RustDesk self-hosted fissa le sue due immagini server invece di seguire un tag mobile: un aggiornamento deve essere un'operazione pianificata per un momento in cui hai tempo di gestirla. Crea sempre un dump prima di procedere.
docker compose pull
sh run.sh recreaterecreate arresta lo stack e lo riavvia usando le nuove immagini. I dati restano disponibili perché risiedono nei bind mount sull'host, non all'interno dei container. Prima di passare a una versione principale successiva, leggi CHANGELOG.md nel repository, perché l'aggiornamento principale di Postgres è un'operazione separata che recreate non esegue. Postgres 17 è la versione predefinita da giugno 2026. Un'installazione esistente su Postgres 15 passa a questa versione con sudo bash utils/upgrade-pg17.sh, che usa pg_upgrade per migrare i dati direttamente e richiede una conferma a ogni passaggio principale. Tutti i container devono essere in esecuzione. Inoltre, serve spazio libero su disco pari almeno al doppio delle dimensioni del database, più 5 GB. Supabase raccomanda comunque di creare un backup indipendente prima di iniziare.
Per applicare le modifiche al file Compose stesso, esegui sh update.sh dalla directory del progetto oppure sh update.sh --dry-run per vedere prima cosa cambierebbe. Il comando unisce i file upstream alle tue modifiche e non sovrascrive i valori esistenti in .env: aggiunge soltanto le nuove chiavi. Prima della scrittura archivia la configurazione in backups/, ma non il database. Un'installazione senza un file .supabase-version richiede --from e la release da cui è stata avviata. Questo è particolarmente importante per la release di agosto 2026, che ha sostituito il servizio kong con api-gw e richiede un aggiornamento docker-compose.yml. È possibile usare anche la procedura manuale: clona nuovamente il repository upstream e copia la directory docker nel progetto, facendo attenzione a non sovrascrivere .env.
Il reset completo, che elimina tutto compreso il database e ripristina .env ai valori predefiniti (quello precedente viene conservato come .env.old), è eseguito da uno script separato che richiede conferma:
sh reset.shFAQ
Perché le chiamate API restituiscono "Invalid authentication credentials"?
Questo messaggio esatto proviene da Kong 2.8, il gateway incluso nello stack delle installazioni precedenti a marzo 2026. Il gateway Envoy predefinito e l'override Kong attuale, che esegue Kong 3.9, segnalano lo stesso problema con un semplice 401 Unauthorized. In entrambi i casi, la chiave inviata non corrisponde a ANON_KEY o SERVICE_ROLE_KEY in .env, oppure tali chiavi non sono state firmate con JWT_SECRET attualmente presente in .env. In uno stack che non ha mai contenuto dati, rigenerare tutti e tre i valori insieme con sh utils/generate-keys.sh --update-env. In uno stack in esecuzione, eseguire lo script senza il flag e rispondere no, in modo che stampi soltanto i nuovi valori; copiare manualmente JWT_SECRET, ANON_KEY e SERVICE_ROLE_KEY in .env e lasciare invariato POSTGRES_PASSWORD. Eseguire quindi sh run.sh recreate affinché i servizi leggano i nuovi valori.
Posso eseguire Supabase self-hosted su un VPS da 2 GB?
Non in modo affidabile. La documentazione ufficiale di self-hosting di Supabase indica 4 GB di RAM come requisito minimo a ottobre 2026. A luglio 2026, una misurazione che includeva i servizi di logging, ora opzionali, mostrava che lo stack utilizzava quasi 3 GB quando era inattivo. Un server da 2 GB perde container a causa dell'out of memory killer e in docker compose ps viene visualizzato il codice di uscita 137. Usare 8 GB in produzione e considerare 4 GB il minimo per lo sviluppo individuale.
Supabase self-hosted include le edge functions?
Sì. Il file Compose include il runtime per le funzioni basato su Deno e serve tutto ciò che viene inserito in ./volumes/functions. Non include la rete globale di distribuzione della piattaforma hosted. Le funzioni vengono quindi eseguite sul singolo server, in un'unica posizione.
Come posso connettermi direttamente al database Postgres?
Usare docker exec -it supabase-db psql -U postgres per aprire una shell interattiva direttamente sul server. Per un client esterno, connettersi tramite Supavisor sulla porta 5432 usando l'utente postgres.<POOLER_TENANT_ID> e il proprio POSTGRES_PASSWORD. Non esporre quella porta a Internet. Raggiungerla tramite una VPN o un tunnel SSH.
Perché i messaggi email di conferma dell'autenticazione contenevano link a localhost?
SITE_URL e API_EXTERNAL_URL in .env erano ancora impostati sui valori predefiniti. Il servizio di autenticazione crea ogni link di conferma e reimpostazione della password a partire da questi due valori. Invia quindi l'indirizzo configurato. Impostare entrambi sull'URL pubblico effettivo e ricreare lo stack.