How to Deploy Supabase on a VPS

#Install Supabase

This guide assumes a box prepared per Docker & Compose on Ubuntu. The setup is a sequence of shell commands rather than a compose file you write yourself — the project ships the compose file and you copy it out of the repository. Clone it (shallow — you only need the current state) and copy the docker/ directory into a clean project folder, including the environment template:

copygit 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

Stop here. Do not run docker compose up yet — the .env you just copied is full of published placeholder secrets, and the next section replaces them first.

#Secrets before first boot — not optional

The .env.example file says it in capitals: you must change all the default values before starting the containers for the first time. The defaults are not weak passwords — they are public knowledge, printed verbatim in the repository and its documentation, including working sample JWTs. A Supabase stack booted with default keys and reachable from the internet is an open database with a friendly dashboard.

The variables that must change, exactly as named in .env:

• POSTGRES_PASSWORD — the database superuser password.
• JWT_SECRET — signs every auth token; anyone holding it can mint valid tokens.
• ANON_KEY and SERVICE_ROLE_KEY — the client-side and server-side API keys. These are JWTs signed by JWT_SECRET, so they must be regenerated together with it — you can't change one and keep the others.
• DASHBOARD_USERNAME and DASHBOARD_PASSWORD — Studio sits behind HTTP basic auth using these; the defaults are supabase / a published placeholder.
• SECRET_KEY_BASE and VAULT_ENC_KEY — internal signing and encryption keys with published defaults.

The repository ships a generator that handles the fiddly part (the JWT-signed API keys). It's in the utils/ folder you already copied:

copysh utils/generate-keys.sh --update-env

That generates fresh values for JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, SECRET_KEY_BASE, VAULT_ENC_KEY, POSTGRES_PASSWORD, DASHBOARD_PASSWORD, and the rest of the secret family, and writes them into .env (keeping a .env.old backup). Set DASHBOARD_USERNAME yourself — the generator leaves it at supabase. Copy the printed ANON_KEY and SERVICE_ROLE_KEY somewhere safe; your client apps need the anon key, and the service-role key belongs only on trusted servers.

Also set the URL variables to match how the stack will actually be reached — SITE_URL, API_EXTERNAL_URL, and SUPABASE_PUBLIC_URL all default to localhost.

Now boot it:

copydocker compose pull
docker compose up -d  #  →  http://SERVER_IP:8000 (Studio via the API gateway)

The pull fetches a dozen images, so the first run takes a while. When it settles, docker compose ps should show every service running or healthy, and the whole stack answers on port 8000 — the API gateway fronts both the APIs and Studio there (the default Envoy gateway serves plain HTTP only — the optional Kong override adds an HTTPS listener on 8443; the pooler exposes Postgres on 5432 for session mode and 6543 for transaction mode). Log into Studio at http://SERVER_IP:8000 with your DASHBOARD_USERNAME / DASHBOARD_PASSWORD.

#Exposing Studio and the API safely

Port 8000 speaks plain HTTP. Basic auth on Studio is the only thing between the internet and your dashboard, and credentials over HTTP are readable in transit — Supabase's own docs tell you to put a reverse proxy with a real TLS certificate in front of the gateway for production, and OAuth logins outright require HTTPS.

Put Caddy in front: proxy your domain to localhost:8000, let Caddy handle certificates, and firewall port 8000 so only localhost reaches the gateway directly. Then update SITE_URL, API_EXTERNAL_URL, and SUPABASE_PUBLIC_URL in .env to the HTTPS domain and restart the stack — env changes only apply on restart. If only you need Studio, consider not publishing it at all and reaching port 8000 over an SSH tunnel or VPN instead; the API is what your apps need public, not the dashboard.

#Backups

Everything that matters lives in two places under your project folder:

• volumes/db/data — the Postgres data directory. Back it up logically with pg_dump against the running database (via the pooler on port 5432, or docker compose exec db pg_dump) on a schedule, and ship the dumps off the box.
• volumes/storage — the actual uploaded files from the Storage service. A database dump does not include these; the Storage API keeps metadata in Postgres but the bytes are on disk here. Rsync or archive this directory alongside the dumps.

A backup that lives only on the same VPS dies with the VPS. Off-box, scheduled, and restore-tested — otherwise it's a guess, and unlike the hosted platform there is no point-in-time recovery to fall back on.

#What breaks compared to the cloud platform

• No automatic upgrades. Nothing updates itself. Moving to newer service images and applying migrations is a manual, read-the-release-notes affair — take a backup first, every time.
• Missing platform features. Branching, managed backups and PITR, advanced metrics beyond logs, ETL, analytics and vector buckets, and the platform management API are hosted-platform features that don't exist here.
• One project per stack. The self-hosted dashboard manages a single project — no organizations, no spinning up a second project next to the first. Want another? That's another compose stack.
• All operations are yours. Monitoring, disaster recovery, scaling, OS patching — the parts of the hosted bill you stopped paying are now paid in your time.

You're done when docker compose ps shows the stack healthy, Studio loads over HTTPS behind your proxy with the credentials you set, a test table created in Studio is readable through the REST API with your regenerated anon key, and a backup of both the database and volumes/storage exists somewhere that isn't this server.