Self-Host Supabase on a VPS

Self-hosted Supabase is a Docker Compose stack of about ten services — Postgres plus the APIs, auth, realtime, storage and dashboard around it — all reached through one API gateway on port 8000. Knowing which container does what is half of debugging a failed install.

Logs and analytics (Logflare and Vector) are not in the default setup; they are an optional add-on that raises memory use. If Docker itself is new to you, Docker hosting explained covers the basics.

Clone a pinned self-hosted/v* release of the Supabase repository, copy its docker/ folder into a project directory, create .env from the example, generate secrets, then start the stack. On Debian, Ubuntu or RHEL-family servers, Supabase also offers a setup script that does all of this, but reading each step once is worth it.

# Pin a release tag; check github.com/supabase/supabase/tags for the latest
git clone --depth 1 --branch self-hosted/v0.8.4 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/. supabase-project
cd supabase-project && cp .env.example .env
printf 'ref=self-hosted/v0.8.4\n' > .supabase-version
docker compose pull

# Generate secrets and the new API keys, then review .env
sh utils/generate-keys.sh
sh utils/add-new-auth-keys.sh

# Start and wait for health checks
sh run.sh start
docker compose ps

After a minute, every service should show Up (healthy). If one is stuck at created, run sh tests/test-container-logs.sh and then sh run.sh logs <service> for the failing one. An entrypoint error from the gateway usually means the files were checked out with Windows CRLF line endings.

Terminate TLS on Nginx at port 443, proxy everything to the gateway on 127.0.0.1:8000, pass the WebSocket upgrade headers for Realtime, and keep port 8000 closed to the internet. Without the upgrade headers, Realtime connects and then drops.

server {
    listen 443 ssl;
    server_name api.example.com;
    # ssl_certificate lines are added by certbot --nginx

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

Issue the certificate with sudo certbot --nginx -d api.example.com, then sudo nginx -t and reload; Certbot SSL on Nginx walks through it. One trap: Docker writes its own iptables rules, so a port published in Compose stays reachable even if ufw denies it. Change the gateway and pooler port mappings in docker-compose.yml to bind to 127.0.0.1 (for example 127.0.0.1:8000:8000), and expose Postgres (5432 and 6543 by default) only if a remote app truly needs it.

Back up two things on a schedule — a Postgres dump and the volumes/storage folder — copy both off the server, and upgrade only with the bundled update.sh after a fresh backup. A database dump alone loses every uploaded file.

#!/bin/sh
# /opt/supabase-backup.sh — run from cron
cd /opt/supabase-project
D=$(date +%F)
docker compose exec -T db pg_dump -U postgres -Fc postgres > /opt/backups/db_$D.dump
tar -czf /opt/backups/storage_$D.tar.gz volumes/storage

Schedule it with 0 3 * * * /opt/supabase-backup.sh >> /var/log/supabase-backup.log 2>&1 (see crontab examples) and ship the files to another machine or object storage, following the 3-2-1 backup rule. Test a restore on a scratch instance before you need it.

Supabase publishes tested self-hosted snapshots about once a month. Read the changelog, back up, then run update.sh, which merges the new configuration over yours. Never run sh reset.sh or docker compose down -v on a live stack: both delete the database and storage data.