Self-Host Supabase on a VPS with Docker and HTTPS

A typical use is a web or mobile application that needs accounts, relational data and uploads. You can keep application code and its backend in a region near your users while controlling the maintenance schedule.

The walkthrough below prepares a fresh Linux VPS for a web/API workflow. Clients reach Supabase through HTTPS, and the database remains accessible within the Docker network. Use a current Docker Compose plugin, with 2.24.4 or newer as the baseline for this guide.

Choose a VPS with room for the full stack

Supabase publishes the following resource guidance for its Docker deployment. Start with the recommended column when planning a production application, then size around measured load. Check the official system requirements.

Allow space for PostgreSQL growth, uploaded files, container images and temporary maintenance work. CPU-intensive queries and image processing can change the requirement substantially. Monitor the real workload after deployment.

HYEHOST offers Cloud VPS and VDS in Wolverhampton, Ashburn and Auckland. Compare the available CPU, RAM and disk allocations before ordering, and check the regional transfer allowance for applications serving frequent downloads.

1. Prepare Linux, DNS and access

Use a fresh Debian or Ubuntu VPS, a sudo-capable administrator account and a domain you control. Point api.example.com to the VPS's public IPv4 address. Add an AAAA record when IPv6 is configured and reachable.

• Allow inbound TCP 80 and 443 for certificate issuance and HTTPS.
• Restrict SSH to the administrators who need it.
• Keep an authenticated SSH session available while changing access rules.
• Check that another application is not already using ports 80 or 443.

Supabase's Linux installer can install Docker and its prerequisites. If you already maintain Docker yourself, check the Engine and Compose versions first. Our installation guide covers Docker on Ubuntu. Follow the Docker setup guide.

2. Fetch the pinned Supabase installer

Create a private working directory in your administrator account. Download the installer from the same release used by this guide and inspect it before running it.

mkdir -p ~/supabase-bootstrap
chmod 700 ~/supabase-bootstrap
cd ~/supabase-bootstrap
curl -fL --output setup.sh \
  https://raw.githubusercontent.com/supabase/supabase/self-hosted/v0.8.4/docker/setup.sh
less setup.sh
sh setup.sh --ref self-hosted/v0.8.4

The pinned installer prepares supabase-project, generates the credentials and keys, records the source version and pulls the images. Run it through a private SSH session because key generation prints credentials. Keep that output within your administrator session. Review the pinned setup script.

Enter your own URLs when prompted. For an application at app.example.com, the intended values are shown below.

SUPABASE_PUBLIC_URL=https://api.example.com
API_EXTERNAL_URL=https://api.example.com/auth/v1
SITE_URL=https://app.example.com
PROXY_DOMAIN=api.example.com

SITE_URL is the frontend destination used by Auth. Confirm it matches your real application. The current callback configuration includes /auth/v1 in API_EXTERNAL_URL. Read the HTTPS configuration guide.

If setup reports an error, resolve it before proceeding. A failed image pull can leave the project prepared but incomplete. Inspect the existing project and its generated configuration before retrying a step.

When the installer adds your account to the Docker group, log out and reconnect so the new group membership takes effect. Then open the project and protect its environment file.

cd ~/supabase-bootstrap/supabase-project
chmod 600 .env
docker version
docker compose version

Retain the generated secrets in .env. Use the supplied files as a compatible set and save your later customisations separately.

3. Enable HTTPS with the supplied Caddy configuration

The release includes a Caddy override that requests a certificate for PROXY_DOMAIN. It sends API traffic to the gateway and protects Studio with the generated dashboard credentials.

sh run.sh config add caddy

The override removes the API gateway's direct host binding on port 8000. Caddy becomes the web entry point. Its configuration lives in volumes/proxy/caddy/Caddyfile. Inspect the supplied Caddy override.

4. Keep the database pooler inside Docker

The base configuration also publishes Supavisor database ports. For this web/API workflow, keep those ports internal. Create docker-compose.private.yml in the project directory with the following content.

services:
  supavisor:
    ports: !reset []

Enable the override and validate the merged configuration.

sh run.sh config add private
sh run.sh config
docker compose config --quiet

!reset clears the inherited port list. Use the current Compose plugin to interpret these override tags. Resolved configuration can contain secrets, so keep detailed inspection within your private administrator session. Read Docker's merge rules.

Applications in this walkthrough use the HTTPS APIs. If your backend later needs a direct PostgreSQL connection, design a restricted private-network or SSH-tunnel path and configure its listener deliberately. Supabase documents its available pooler and connection modes. Review PostgreSQL access options.

After startup, inspect published ports and test access from another machine over each configured IP family. Our Docker firewall guide explains how published ports interact with host firewall rules. Check Docker port exposure.

5. Start the stack and verify its health

sh run.sh pull
sh run.sh start
docker compose ps
docker compose logs --tail=100 api-gw auth db caddy

Wait for the services to become healthy. Investigate an unhealthy service before connecting your application. The release's management helper wraps Compose operations and applies the configured override files. Read the management helper.

Open https://api.example.com and sign in to Studio using the generated dashboard username and password from .env. Use your own domain in every command and browser check.

For an authenticated Auth health check, substitute your generated publishable key locally.

curl --fail --show-error \
  https://api.example.com/auth/v1/health \
  --header 'apikey: YOUR_PUBLISHABLE_KEY'

The response should identify the running Auth service. Check certificate validity, service health and an actual application operation as separate steps. Supabase provides a current Auth version-check procedure. Verify the Auth service.

6. Configure application keys and data permissions

Supabase's key documentation describes how publishable and secret keys map to database access. Set policies for the actual data model before connecting real customer information. Test signed-out access and two different signed-in users. Check API key handling. Configure Row Level Security.

For email sign-in and recovery, configure a working SMTP service, sender identity and appropriate limits. Test signup, confirmation and password recovery end to end. Self-hosted Auth settings are managed through server configuration. Review Auth configuration.

If you enable a social provider, register its callback URL and configure the allowed frontend redirects. For this hostname, the callback is https://api.example.com/auth/v1/callback. Recreate affected containers after changing their environment. Follow the OAuth configuration guide.

When adding Edge Functions, implement the authentication and authorisation required by each function. Review the release's verification settings and test requests with valid and missing credentials before exposing the endpoint. Read the self-hosted Functions guide.

7. Back up the database, objects and keys together

Build a recovery plan before the application holds irreplaceable data. Define a recovery point that keeps database metadata and uploaded objects consistent, then retain enough history to recover from an accidental deletion.

The default stack stores uploaded objects on local disk. Database exports cover their metadata, while object contents need their own recovery copy. Supabase describes the storage backends and the scope of its database restore workflow. Review Storage configuration. Read the database restore guidance.

Include the db-config named volume in a recovery method that preserves the existing database's encryption state. The supplied Compose file uses it to persist the pgsodium decryption key. Keep its recovery material with the protected configuration and database backups. Check the pinned volume definitions.

Use a coordinated database backup or a cleanly stopped deployment when your method requires filesystem consistency. Encrypt the off-server copy and test restoration on a separate machine. Verify login, API queries, a file download and the relevant keys after recovery.

A HYEHOST Storage Box can hold encrypted recovery archives through SFTP or another supported access method. Our Rclone guide covers an encrypted off-server copy. Set up encrypted backup storage.

8. Rehearse updates and watch capacity

Retain .supabase-version and review the self-hosted changelog before upgrading. The provided updater can preview its plan.

sh update.sh --dry-run

Follow the release's update procedure on a staging copy, resolve configuration conflicts and verify your custom override afterwards. Protect database and Storage data with your recovery process before applying changes. The updater's automatic archive covers configuration files. Read the update procedure.

Monitor RAM, disk space, database connections, application response time and backup age. External uptime checks help detect a failed server or certificate issue. Watch public transfer when the application serves uploaded files, especially on plans with a regional transfer allowance.

Common Supabase VPS setup problems

Self-hosted Supabase FAQ