Self-Hosting with Docker

Learn how to configure and deploy Supabase with Docker.

Docker is the easiest way to get started with self-hosted Supabase. This guide assumes you are running the command from the machine you intend to host from.

Before you begin#

You need the following installed in your system: Git and Docker (Windows, MacOS, or Linux).

Running Supabase#

Running a self-hosted Supabase project is simple. Follow the steps below:

Now visit localhost:3000 to start using Supabase Studio.

That's everything you need to get started. The rest of this guide will help you to customize your setup.

Securing your setup#

While we provided you with some example secrets for getting started, you should NEVER deploy your Supabase setup using the defaults we have provided.

Generate API Keys#

Create a new JWT_SECRET and store it securely.

We can use your JWT Secret to generate new anon and service API keys using the form below. Update the "JWT Secret" and then run "Generate JWT" once for the SERVICE_KEY and once for the ANON_KEY:

Update API Keys#

Replace the values in these files:

• .env:
  • ANON_KEY - replace with an anon key
  • SERVICE_ROLE_KEY - replace with a service key
• volumes/api/kong.yml
  • anon - replace with an anon key
  • service_role - replace with a service key

Update Secrets#

Update the .env file with your own secrets. In particular, these are required:

• POSTGRES_PASSWORD: the password for the postgres role.
• JWT_SECRET: used by PostgREST and GoTrue, among others.
• SITE_URL: the base URL of your site.
• SMTP_*: mail server credentials. You can use any SMTP server.

Exposing services#

The services running on the machine are not exposed to the internet by default. We recommend using a reverse proxy such as NGINX or Caddy if you want to expose the services publicly:

1. Install Caddy using the official instructions.
2. Modify the Caddyfile at ./docker/deploy/caddy/Caddyfile.
   1. Replace localhost with your domain.
   2. Uncomment the "Dashboard" section if you want to expose the Supabase Dashboard. You MUST set a password for this to be secure.
3. Run caddy run --config ./docker/deploy/caddy/Caddyfile to start Caddy.

You can now access your services at the following URLs:

• REST: https://<your-domain>/proxy/rest/v1/
• Auth: https://<your-domain>/proxy/auth/v1/
• Storage: https://<your-domain>/proxy/storage/v1/
• Functions: https://<your-domain>/proxy/functions/v1/
• Realtime: https://<your-domain>/proxy/realtime/v1/
• Dashboard: https://<your-domain>/ (if you uncommented the Dashboard section in the Caddyfile)

Stop#

You can stop Supabase by running docker compose stop in same directory as your docker-compose.yml file.

Uninstall#

You can stop Supabase by running docker compose down -v in same directory as your docker-compose.yml file.

Advanced configuration#

Each system can be configured independently. Some of the most important configuration options are:

• Consider deploying the database to a different server than the rest of the services
• Update Storage to use S3 instead of the filesystem backend
• Configure Auth with a production-ready SMTP server

Setting up Edge Functions#

Your Functions are stored in volumes/functions. The default setup has a hello Function that you can invoke on http://localhost:8000/functions/v1/hello. You can add new Functions as volumes/functions/<Function name>/index.ts.

Using an external database#

We strongly recommend decoupling your database from docker-compose before deploying. The middleware will run with any PostgreSQL database that has logical replication enabled. The following environment variables should be updated in the .env file to point to your external database:

Once you have done this, you can safely comment out the db section of the docker-compose file, and remove any instances where the services depends_on the db image.

Supabase services require your external database to be initialized with a specific schema. Refer to our postgres/migrations repository for instructions on running these migrations.

Note that you need superuser permission on the postgres role to perform the initial schema migration. Once completed, the postgres role will be demoted to non-superuser to prevent abuse.

Setting database's log_min_messages#

By default, docker compose sets the database's log_min_messages configuration to fatal to prevent redundant logs generated by Realtime. However, you might miss important log messages such as database errors. Configure log_min_messages based on your needs.

File storage backend on macOS#

By default, Storage backend is set to file, which is to use local files as the storage backend. To make it work on macOS, you need to choose VirtioFS as the Docker container file sharing implementation (in Docker Desktop -> Preferences -> General).