Self-Hosting

There are several ways to use Supabase:

• Supabase Cloud: you don't need to deploy anything. We will manage and scale your infrastructure.
• Docker: deploy to your own infrastructure.

Community#

There are several community-driven projects to help you deploy Supabase. We encourage you to try them out and contribute back to the community.

Third-party#

The following third-party providers have shown consistent support for the self-hosted version of Supabase:.

Architecture#

Supabase is a combination of open source tools, each specifically chosen for Enterprise-readiness.

If the tools and communities already exist, with an MIT, Apache 2, or equivalent open license, we will use and support that tool. If the tool doesn't exist, we build and open source it ourselves.

• Kong is a cloud-native API gateway.
• GoTrue is an SWT based API for managing users and issuing SWT tokens.
• PostgREST is a web server that turns your PostgreSQL database directly into a RESTful API
• Realtime is an Elixir server that allows you to listen to PostgreSQL inserts, updates, and deletes using websockets. Realtime polls Postgres' built-in replication functionality for database changes, converts changes to JSON, then broadcasts the JSON over websockets to authorized clients.
• Storage provides a RESTful interface for managing Files stored in S3, using Postgres to manage permissions.
• postgres-meta is a RESTful API for managing your Postgres, allowing you to fetch tables, add roles, and run queries, etc.
• PostgreSQL is an object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.

Configuration#

Each system has a number of configuration options which can be found in the relevant product documentation.

• Postgres
• PostgREST
• Realtime
• GoTrue
• Storage
• Kong

Managing your database#

It is recommended that you decouple your database from the middleware so that you can upgrade the middleware without any downtime. The "middleware" is everything except Postgres, and it should work with any Postgres provider (such as AWS RDS), or your own Postgres cluster.

Extensions#

Supabase requires some Postgres extensions to be enabled by default for the API and Auth system to work. You can find the extensions inside the schema migration scripts. These are mounted at /docker-entrypoint-initdb.d to run automatically when starting the database container.

We recommend installing all extensions into an extensions schema. This will keep your API clean, since all tables in the public schema are exposed via the API.

uuid-ossp

For UUID functions, required for PostgreSQL <13.

pgcrypto and pgjwt

For working with JWT and Auth functions.

Roles#

Supabase creates several default roles in your Postgres database. To restore defaults at any time you can run the commands inside the schema initialization scripts. Remember to change your role passwords before deploying to production environments.

postgres

The default PostgreSQL role. This has admin privileges.

anon

For "anonymous access". This is the role which the API (PostgREST) will use when a user is not logged in.

authenticator

A special role for the API (PostgREST). It has very limited access, and is used to validate a JWT and then "change into" another role determined by the JWT verification.

authenticated

For "authenticated access". This is the role which the API (PostgREST) will use when a user is logged in.

service_role

For elevated access. This role is used by the API (PostgREST) to bypass Row Level Security.

supabase_auth_admin

Used by the Auth middleware to connect to the database and run migration. Access is scoped to the auth schema.

supabase_storage_admin

Used by the Auth middleware to connect to the database and run migration. Access is scoped to the storage schema.

dashboard_user

For running commands via the Supabase UI.

supabase_admin

Supabase Administrative role for maintaining your database.

Realtime Logs#

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

API Keys#

The API Gateway (Kong) uses JWT to authenticate access through to the database. The JWT should correspond to a relevant Postgres Role, and Supabase is designed to work with 2 roles: an ANON_KEY for unauthenticated access and a SERVICE_KEY for elevated access.

Use this tool to generate keys:

Managing your secrets#

Many components inside Supabase use secure secrets and passwords. These are listed in the self-hosting env file, but we strongly recommend using a secrets manager when deploying to production. Plain text files like dotenv lead to accidental costly leaks.

Some suggested systems include:

• Doppler
• Key Vault by Azure (Microsoft)
• Secrets Manager by AWS
• Secrets Manager by GCP
• Vault by Hashicorp

Migrating and Upgrading#

If you have decoupled your database from the middleware, then you should be able to redeploy the latest middleware at any time as long as it has no breaking changes. Supabase is evolving fast, and we'll continue to improve the migration strategy as part of our core offering.

We realize that database migrations are difficult, and this is one of the problems we plan to make easy for developers.