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:

After all the services have started you should be able to see them running in the background:

Now visit localhost:8000 to start using Supabase Studio. You will be prompted for a username and password. By default, the username is supabase and the password is this_password_is_insecure_and_should_be_updated. Please update the Dashboard Authentication as soon as possible using the instructions below.

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 the .env file:

• ANON_KEY - replace with an anon key
• SERVICE_ROLE_KEY - replace with a service key

You will need to restart the services for the changes to take effect.

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.

You will need to restart the services for the changes to take effect.

Dashboard Authentication#

The dashboard is protected with Basic Authentication. The default user and password MUST be updated before using Supabase in production. You can update the ./docker/volumes/api/kong.yml file with your own credentials. For example:

You will need to restart the services for the changes to take effect.

Restart#

You can restart services to pick up any configuration changes by running:

Be aware that this will result in downtime while the services are restarting.

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).

Setting up logging with the Analytics server#

Additional configuration is required for self-hosting the Analytics server. For the full setup instructions, see Self Hosting Analytics.