rembrembdocs
← supabaseoriginal source ↗

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. It should take you less than 30 minutes to get up and running.

Contents#

  1. Before you begin
  2. System requirements
  3. Installing Supabase
  4. Configuring and securing Supabase
  5. Starting and stopping
  6. Accessing Supabase services
  7. Updating
  8. Uninstalling
  9. Advanced topics

Before you begin#

This guide assumes you're comfortable with:

If you're new to these topics, consider starting with managed Supabase platform for free.

You need the following installed on your system:

System requirements#

Minimum requirements for running all Supabase components, suitable for development and small to medium production workloads:

Resource

Minimum

Recommended

RAM

4 GB

8 GB+

CPU

2 cores

4 cores+

Disk

50 GB SSD

80 GB+ SSD

If you don't need specific services, such as Logflare (Analytics), Realtime, Storage, imgproxy, or Edge Runtime (Functions), you can remove the corresponding sections and dependencies from docker-compose.yml to reduce resource requirements.

Installing Supabase#

Follow these steps to start Supabase on your machine:

1# Get the code2git clone --depth 1 https://github.com/supabase/supabase34# Make your new supabase project directory5mkdir supabase-project67# Tree should look like this8# .9# ├── supabase10# └── supabase-project1112# Copy the compose files over to your project13cp -rf supabase/docker/* supabase-project1415# Copy the fake env vars16cp supabase/docker/.env.example supabase-project/.env1718# Switch to your project directory19cd supabase-project2021# Pull the latest images22docker compose pull

If you are using rootless Docker, edit .env and set DOCKER_SOCKET_LOCATION to your docker socket location. For example: /run/user/1000/docker.sock. Otherwise, you will see an error like container supabase-vector exited (0).

Configuring and securing Supabase#

While we provided example placeholder passwords and keys in the .env.example file, you should NEVER start your self-hosted Supabase using these defaults.

Review the configuration options below and ensure you set all secrets before starting the services.

Quick setup (experimental)#

To generate and apply all secrets at once you can run:

1sh ./utils/generate-keys.sh

Review the output before proceeding and also check .env after it's updated by the script. Alternatively, configure all secrets manually as follows.

Configure database password#

Change the placeholder password in the .env file before starting Supabase for the first time.

Follow the password guidelines for choosing a secure password. For easier configuration, use only letters and numbers to avoid URL encoding issues in connection strings.

Generate and configure API keys#

Use the key generator below to obtain and configure the following secure keys in .env:

JWT_SECRET

gl75NNvXePv1ECitebEeP6XU3OxEbnlNNB25w1Qx

ANON_KEY

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzc2NDcwNDAwLCJleHAiOjE5MzQyMzY4MDB9.CD7gLbWpGWUZlsFTOOUJbwwZlxgGY4I2ykD17jRxTa8

SERVICE_ROLE_KEY

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIiwiaXNzIjoic3VwYWJhc2UiLCJpYXQiOjE3NzY0NzA0MDAsImV4cCI6MTkzNDIzNjgwMH0.cYK6bcbSadvHalD4mPS9LZRX4hOC3Zx4kuplqsPngso
  1. Copy the generated value and update JWT_SECRET in the .env file. Do not share this secret publicly or commit it to version control.
  2. Copy the generated value and update ANON_KEY in the .env file.
  3. Copy the generated value and update SERVICE_ROLE_KEY in the .env file.

The generated keys expire in 5 years. You can verify them at jwt.io using the saved value of JWT_SECRET.

Configure other keys, and important URLs#

Edit the following settings in the .env file:

Review and change URL environment variables:

If you are only using self-hosted Supabase locally, you can use localhost.

Studio authentication#

Access to Studio dashboard and internal API is protected with HTTP basic authentication.

The default password MUST be changed before starting Supabase.

The password must include at least one letter: do not use numbers only and do not use any special characters.

Change the password in the .env file:

Optionally change the user:

Starting and stopping#

You can start all services by using the following command in the same directory as your docker-compose.yml file:

1# Start the services (in detached mode)2docker compose up -d

After all the services have started you can see them running in the background:

1docker compose ps

After a minute or less, all services should have a status Up [...] (healthy). If you see a status such as created but not Up, try inspecting the Docker logs for a specific container, e.g.,

1docker compose logs analytics

To stop Supabase, use:

1docker compose down

Accessing Supabase services#

After the Supabase services are configured and running, you can access the dashboard, connect to the database, and use edge functions.

Accessing Supabase Studio#

You can access Supabase Studio through the API gateway on port 8000.

For example: http://example.com:8000, or http://<your-ip>:8000 (or localhost:8000 if you are running Docker Compose locally).

You will be prompted for a username and password. Use the credentials that you set up earlier in Studio authentication.

Accessing Postgres#

By default, the Supabase stack provides the Supavisor connection pooler for accessing Postgres and managing database connections.

You can connect to the Postgres database via Supavisor using the methods described below. Use your domain name, your server IP, or localhost depending on whether you are running self-hosted Supabase on a VPS, or locally.

The default POOLER_TENANT_ID is your-tenant-id (can be changed in .env), and the password is the one you set previously in Configure database password.

For session-based connections (equivalent to a direct Postgres connection):

1psql 'postgres://postgres.[POOLER_TENANT_ID]:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres'

For pooled transactional connections:

1psql 'postgres://postgres.[POOLER_TENANT_ID]:[POSTGRES_PASSWORD]@[your-domain]:6543/postgres'

When using psql with command-line parameters instead of a connection string to connect to Supavisor, the -U parameter should also be postgres.[POOLER_TENANT_ID], and not just postgres.

If you need to configure Postgres to be directly accessible from the Internet, read Exposing your Postgres database.

To change the database password, read Changing database password.

Accessing Edge Functions#

Edge Functions are stored in volumes/functions. The default setup has a hello function that you can invoke on http://<your-domain>:8000/functions/v1/hello.

You can add new Functions as volumes/functions/<FUNCTION_NAME>/index.ts. Restart the functions service to pick up the changes: docker compose restart functions --no-deps

Accessing the APIs#

Each of the APIs is available through the same API gateway:

Updating#

We publish stable releases of the Docker Compose setup approximately once a month. To update, apply the latest changes from the repository and restart the services. If you want to run different versions of individual services, you can change the image tags in the Docker Compose file, but compatibility is not guaranteed. All Supabase images are available on Docker Hub.

To follow the changes and updates, refer to the self-hosted Supabase changelog.

You need to restart services to pick up the changes, which may result in downtime for your applications and users.

Example: You'd like to update or rollback the Studio image. Follow the steps below:

  1. Check the supabase/studio images on Supabase Docker Hub
  2. Find the latest version (tag) number. It looks something like 2025.11.26-sha-8f096b5
  3. Update the image field in the docker-compose.yml file. It should look like this: image: supabase/studio:2025.11.26-sha-8f096b5
  4. Run docker compose pull, followed by docker compose down && docker compose up -d to restart Supabase.

Uninstalling#

Be careful — the following destroys all data, including the database and storage volumes!

To uninstall, stop Supabase (while in the same directory as your docker-compose.yml file):

1# Stop docker and remove volumes:2docker compose down -v

Optionally, ensure removal of all Postgres data:

1rm -rf volumes/db/data

and all Storage data:

1rm -rf volumes/storage

Advanced topics#

Everything beyond this point in the guide helps you understand how the system works and how you can modify it to suit your needs.

Architecture#

Supabase is a combination of open source tools specifically developed for enterprise-readiness.

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

Diagram showing the architecture of Supabase. The Kong API gateway sits in front of 7 services: GoTrue, PostgREST, Realtime, Storage, pg_meta, Functions, and pg_graphql. All the services talk to a single Postgres instance.

Multiple services require specific configuration within the Postgres database. Refer to the documentation describing the default roles to learn more.

You can find all the default extensions inside the schema migration scripts repo. These scripts are mounted at /docker-entrypoint-initdb.d to run automatically when starting the database container.

Configuring services#

Each service has a number of configuration options you can find in the related documentation.

Configuration options are generally added to the .env file and referenced in docker-compose.yml service definitions, e.g.,

1services:2  rest:3    image: postgrest/postgrest4    environment:5      PGRST_JWT_SECRET: ${JWT_SECRET}

Common configuration tasks#

You can configure each Supabase service separately through environment variables and configuration files. Below are the most common configuration options.

Configuring an email server#

You will need to use a production-ready SMTP server for sending emails. You can configure the SMTP server by updating the following environment variables in the .env file:

1SMTP_ADMIN_EMAIL=2SMTP_HOST=3SMTP_PORT=4SMTP_USER=5SMTP_PASS=6SMTP_SENDER_NAME=

We recommend using AWS SES. It's affordable and reliable. Restart all services to pick up the new configuration.

Configuring S3 Storage#

By default all files are stored locally on the server. You can connect Storage to an S3-compatible backend (AWS S3, MinIO, Cloudflare R2), enable the S3 protocol endpoint for tools like rclone, or both. These are independent features.

See the Configure S3 Storage guide for detailed setup instructions.

Configuring HTTPS#

By default, Supabase is accessible over HTTP. For production deployments, especially when using OAuth providers, you need HTTPS with a valid TLS certificate. The recommended approach is to place a reverse proxy (such as Caddy or Nginx) in front of Kong.

See the Configure HTTPS guide for setup instructions.

Configuring social login (OAuth) providers#

See the Configure Social Login (OAuth) Providers guide for setup instructions.

Configuring phone login, SMS, and MFA#

See the Configure Phone Login & MFA guide for SMS provider setup, OTP settings, and multi-factor authentication configuration.

Configuring Supabase AI Assistant#

Configuring the Supabase AI Assistant is optional. By adding your own OPENAI_API_KEY to .env you can enable AI services, which help with writing SQL queries, statements, and policies.

Setting log_min_messages in Postgres#

By default, the database's log_min_messages configuration is set to fatal in docker-compose.yml to prevent redundant logs generated by Realtime. You can configure log_min_messages using any of the Postgres Severity Levels.

Accessing Postgres through Supavisor#

By default, Postgres connections go through the Supavisor connection pooler for efficient connection management. Two ports are available:

For more information on configuring and using Supavisor, see the Supavisor documentation.

Exposing your Postgres database#

By default, Postgres is only accessible through Supavisor. If you need direct access to the database (bypassing the connection pooler), you need to disable Supavisor and expose the Postgres port.

Exposing Postgres directly bypasses connection pooling and exposes your database to the network. Configure firewall rules or network policies to restrict access to trusted IPs only.

Edit docker-compose.yml:

  1. Disable Supavisor - Comment out or remove the entire supavisor service section
  2. Expose Postgres port - Add the port mapping to the db service, it should look like the example below:
1db:2  ports:3    - ${POSTGRES_PORT}:${POSTGRES_PORT}4  container_name: supabase-db

After restarting, you can connect to the database directly using a standard Postgres connection string:

1postgres://postgres:[POSTGRES_PASSWORD]@[your-server-ip]:5432/[POSTGRES_DB]

Changing database password#

To change the database password after initial setup, run:

1sh ./utils/db-passwd.sh

The script generates a new password, updates all database roles, and modifies your .env file. After running it, restart the services with docker compose up -d --force-recreate.

File storage backend on macOS#

By default, Storage backend is set to file, which is to use local files as the storage backend. If using Docker Desktop on a Mac, choose VirtioFS as the Docker container file sharing implementation (in Preferences > General).

Managing your secrets#

Many components inside Supabase use secure secrets and passwords. These are kept in the .env file, but we strongly recommend using a secrets manager when deploying to production.

Some suggested systems include:

Demo#

  1. The VPS instance is a DigitalOcean droplet. (For server requirements refer to System requirements)
  2. To access Studio, use the IPv4 IP address of your Droplet.
  3. If you're unable to use Studio, run docker compose ps to see if all services are up and healthy.