Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

update .env.example with better comments

Andrey A.aa1aa7320006
diff --git a/apps/docs/content/guides/self-hosting/docker.mdx b/apps/docs/content/guides/self-hosting/docker.mdx
index 500dafdef29..74146dcdc8d 100644
--- a/apps/docs/content/guides/self-hosting/docker.mdx
+++ b/apps/docs/content/guides/self-hosting/docker.mdx
@@ -145,9 +145,7 @@ To generate and apply all secrets at once you can run:
sh ./utils/generate-keys.sh
```
-The script is experimental, so review the output before proceeding and also check `.env` after it's updated by the script.
-
-**Alternatively, configure all secrets manually as follows.**
+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
@@ -161,10 +159,9 @@ Follow the [password guidelines](/docs/guides/database/postgres/roles#passwords)
Use the key generator below to obtain and configure the following secure keys in `.env`:
-- `JWT_SECRET`: Used by PostgREST and GoTrue to sign and verify JWTs.
+- `JWT_SECRET`: Used by Auth, PostgREST, and other services to sign and verify JWTs.
- `ANON_KEY`: Client-side API key with limited permissions (`anon` role). Use this in your frontend applications.
-- `SERVICE_ROLE_KEY`: Server-side API key with full database access (`service_role` role). Never expose this in client code.
-
+- `SERVICE_ROLE_KEY`: Server-side API key with full database access (`service_role` role). **Never expose this in client code.**
<JwtGeneratorSimple />
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.
@@ -182,16 +179,16 @@ Edit the following settings in the `.env` file:
- `PG_META_CRYPTO_KEY`: encryption key for securing connection strings used by Studio against postgres-meta. (Must be at least 32 characters; generate with `openssl rand -base64 24`)
- `LOGFLARE_PUBLIC_ACCESS_TOKEN`: API token for log ingestion and querying. Used by Vector and Studio to send and query logs. (Must be at least 32 characters; generate with `openssl rand -base64 24`)
- `LOGFLARE_PRIVATE_ACCESS_TOKEN`: API token for Logflare management operations. Used by Studio for administrative tasks. Never expose client-side. (Must be at least 32 characters; generate with `openssl rand -base64 24`)
-- `S3_PROTOCOL_ACCESS_KEY_ID`: Access key ID (username-like) for authenticating API requests to S3-compatible storage. (Generate with `openssl rand -hex 16`)
-- `S3_PROTOCOL_ACCESS_KEY_SECRET`: Secret key (password-like) used with S3_PROTOCOL_ACCESS_KEY_ID to sign and authorize S3 storage operations. (Generate with `openssl rand -hex 32`)
+- `S3_PROTOCOL_ACCESS_KEY_ID`: Access key ID (username-like) for [accessing](/docs/guides/self-hosting/self-hosted-s3) the S3 protocol endpoint in Storage. (Generate with `openssl rand -hex 16`)
+- `S3_PROTOCOL_ACCESS_KEY_SECRET`: Secret key (password-like) used with S3_PROTOCOL_ACCESS_KEY_ID. (Generate with `openssl rand -hex 32`)
{/* supa-mdx-lint-disable-next-line Rule003Spelling */}
-- `MINIO_ROOT_PASSWORD`: Root administrator password for the MinIO server. (Must be 8+ characters; generate with `openssl rand -hex 16`)
+- `MINIO_ROOT_PASSWORD`: Root administrator password for the [MinIO server](/docs/guides/self-hosting/self-hosted-s3#using-minio). (Must be 8+ characters; generate with `openssl rand -hex 16`)
Review and change URL environment variables:
-- `SUPABASE_PUBLIC_URL`: the base URL for accessing your Supabase via the Internet, e.g, `http://example.com:8000`
-- `API_EXTERNAL_URL`: the base URL for API requests, e.g., `http://example.com:8000`
-- `SITE_URL`: the base URL of your site, e.g., `http://example.com:3000`
+- `SUPABASE_PUBLIC_URL`: base URL for accessing Supabase from the Internet (Dashboard, API, Storage, etc.), e.g, `http://example.com:8000`
+- `API_EXTERNAL_URL`: base URL of the Auth service as seen externally, e.g., `http://example.com:8000`
+- `SITE_URL`: default [redirect URL](/docs/guides/auth/redirect-urls) for Auth, e.g., `http://example.com:3000`
<Admonition type="tip">
@@ -412,7 +409,7 @@ You can configure each Supabase service separately through environment variables
#### 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:
+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:
```sh .env
SMTP_ADMIN_EMAIL=
@@ -423,7 +420,7 @@ SMTP_PASS=
SMTP_SENDER_NAME=
```
-We recommend using [AWS SES](https://aws.amazon.com/ses/). It's extremely cheap and reliable. Restart all services to pick up the new configuration.
+We recommend using [AWS SES](https://aws.amazon.com/ses/). It's affordable and reliable. Restart all services to pick up the new configuration.
#### Configuring S3 Storage
{/* supa-mdx-lint-disable-next-line Rule003Spelling */}
@@ -433,35 +430,18 @@ See the [Configure S3 Storage](/docs/guides/self-hosting/self-hosted-s3) guide f
#### Configuring Supabase AI Assistant
-Configuring the Supabase AI Assistant is optional. By adding your own `OPENAI_API_KEY`, you can enable AI services, which help with writing SQL queries, statements, and policies.
-
-<$CodeTabs>
-
-```yaml name=docker-compose.yml
-services:
- studio:
- image: supabase/studio
- environment:
- OPENAI_API_KEY: ${OPENAI_API_KEY:-}
-```
-
-```bash name=.env
-## Never check your secrets into version control
-`${OPENAI_API_KEY}`
-```
-
-</$CodeTabs>
+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 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. You can configure `log_min_messages` using any of the Postgres [Severity Levels](https://www.postgresql.org/docs/current/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS).
+By default, the database's `log_min_messages` configuration is set to `fatal` in [docker-compose.yml](https://github.com/supabase/supabase/blob/df8729a82b1847e2989c14ede27965612761d503/docker/docker-compose.yml#L466) to prevent redundant logs generated by Realtime. You can configure `log_min_messages` using any of the Postgres [Severity Levels](https://www.postgresql.org/docs/current/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS).
#### Accessing Postgres through Supavisor
By default, Postgres connections go through the Supavisor connection pooler for efficient connection management. Two ports are available:
-- `POSTGRES_PORT` (default: 5432) – Session mode, behaves like a direct Postgres connection
-- `POOLER_PROXY_PORT_TRANSACTION` (default: 6543) – Transaction mode, uses connection pooling
+- `POSTGRES_PORT` (default: 5432) - Session mode, behaves like a direct Postgres connection
+- `POOLER_PROXY_PORT_TRANSACTION` (default: 6543) - Transaction mode, uses connection pooling
For more information on configuring and using Supavisor, see the [Supavisor documentation](https://supabase.github.io/supavisor/).
@@ -505,7 +485,7 @@ The script generates a new password, updates all database roles, and modifies yo
#### File storage backend on macOS
-By default, Storage backend is set to `file`, which is to use local files as the storage backend. For macOS compatibility, you need to choose `VirtioFS` as the Docker container file sharing implementation (in Docker Desktop -> Preferences -> General).
+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
diff --git a/docker/.env.example b/docker/.env.example
index 31fd8c75167..5fcff319982 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -1,70 +1,126 @@
############
# Secrets
-# YOU MUST CHANGE THESE BEFORE GOING INTO PRODUCTION
-############
-
+#
+# YOU MUST CHANGE ALL THE DEFAULT VALUES BELOW BEFORE STARTING
+# THE CONTAINERS FOR THE FIRST TIME!
+#
+# Documentation:
+# https://supabase.com/docs/guides/self-hosting/docker#configuring-and-securing-supabase
+#
+# To generate secrets and API keys:
+# sh ./utils/generate-keys.sh
+#
+############
+
+# Postgres
POSTGRES_PASSWORD=your-super-secret-and-long-postgres-password
+
+# Symmetric encryption key and JWT API keys
JWT_SECRET=your-super-secret-jwt-token-with-at-least-32-characters-long
ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyAgCiAgICAicm9sZSI6ICJhbm9uIiwKICAgICJpc3MiOiAic3VwYWJhc2UtZGVtbyIsCiAgICAiaWF0IjogMTY0MTc2OTIwMCwKICAgICJleHAiOiAxNzk5NTM1NjAwCn0.dc_X5iR_VP_qT0zsiyj_I_OZ2T9FtRU2BBNWN8Bu4GE
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyAgCiAgICAicm9sZSI6ICJzZXJ2aWNlX3JvbGUiLAogICAgImlzcyI6ICJzdXBhYmFzZS1kZW1vIiwKICAgICJpYXQiOiAxNjQxNzY5MjAwLAogICAgImV4cCI6IDE3OTk1MzU2MDAKfQ.DaYlNEoUrrEn2Ig7tqibS-PHK5vgusbcbo7X36XVt4Q
+
+# Access to Dashboard
DASHBOARD_USERNAME=supabase
DASHBOARD_PASSWORD=this_password_is_insecure_and_should_be_updated
+
+# Used by Realtime and Supavisor
SECRET_KEY_BASE=UpNVntn3cDxHJpq99YMc1T1AQgQpc8kfYTuRgBiYa15BLrx8etQoXz3gZv1/u2oq
+
+# Used by Supavisor
VAULT_ENC_KEY=your-32-character-encryption-key
+
+# Used by Studio to access Postgres via postgres-meta
PG_META_CRYPTO_KEY=your-encryption-key-32-chars-min
+# Analytics - API tokens for log ingestion/querying, and for management
+LOGFLARE_PUBLIC_ACCESS_TOKEN=your-super-secret-and-long-logflare-key-public
+LOGFLARE_PRIVATE_ACCESS_TOKEN=your-super-secret-and-long-logflare-key-private
+
+# Access to Storage via S3 protocol endpoint (see below)
+S3_PROTOCOL_ACCESS_KEY_ID=625729a08b95bf1b7ff351a663f3a23c
+S3_PROTOCOL_ACCESS_KEY_SECRET=850181e4652dd023b7a98c58ae0d2d34bd487ee0cc3254aed6eda37307425907
+
############
-# Database - You can change these to any PostgreSQL database that has logical replication enabled.
+# URLs - Configure hostnames below to reflect your actual domain name
############
+# Access Dashboard and REST API
+SUPABASE_PUBLIC_URL=http://localhost:8000
+
+# Full external URL of the Auth service, used to construct OAuth callbacks,
+# SAML endpoints, and email links
+API_EXTERNAL_URL=http://localhost:8000
+
+# See also the Auth section below for Site URL and Redirect URLs configuration
+
+
+############
+# Database - Postgres configuration
+############
+
+# Using default user (postgres)
POSTGRES_HOST=db
POSTGRES_DB=postgres
+
+# Default configuration includes Supavisor exposing POSTGRES_PORT
+# Postgres uses POSTGRES_PORT inside the container
+# Documentation:
+# https://supabase.com/docs/guides/self-hosting/docker#accessing-postgres-through-supavisor
POSTGRES_PORT=5432
-# default user is postgres
############
-# Supavisor -- Database pooler
+# Supavisor - Database pooler
############
-# Port Supavisor listens on for transaction pooling connections
+
+# Supavisor exposes POSTGRES_PORT and POOLER_PROXY_PORT_TRANSACTION,
+# POSTGRES_PORT is used for session mode pooling
+#
+# Port to use for transaction mode pooling connections
POOLER_PROXY_PORT_TRANSACTION=6543
+
# Maximum number of PostgreSQL connections Supavisor opens per pool
POOLER_DEFAULT_POOL_SIZE=20
+
# Maximum number of client connections Supavisor accepts per pool
POOLER_MAX_CLIENT_CONN=100
-# Unique tenant identifier
+
+# Unique Supavisor tenant identifier
+# Documentation:
+# https://supabase.com/docs/guides/self-hosting/docker#accessing-postgres
POOLER_TENANT_ID=your-tenant-id
+
# Pool size for internal metadata storage used by Supavisor
# This is separate from client connections and used only by Supavisor itself
POOLER_DB_POOL_SIZE=5
############
-# API Proxy - Configuration for the Kong Reverse proxy.
+# Studio - Configuration for the Dashboard
############
-KONG_HTTP_PORT=8000
-KONG_HTTPS_PORT=8443
-
-
-############
-# API - Configuration for PostgREST.
-############
+STUDIO_DEFAULT_ORGANIZATION=Default Organization
+STUDIO_DEFAULT_PROJECT=Default Project
-PGRST_DB_SCHEMAS=public,storage,graphql_public
+# Add your OpenAI API key to enable AI Assistant
+OPENAI_API_KEY=sk-proj-xxxxxxxx
############
-# Auth - Configuration for the GoTrue authentication server.
+# Auth - Configuration for the authentication server
############
-## General
+## General settings
+
+# Equivalent to "Site URL" and "Redirect URLs" platform configuration options
+# Documentation: https://supabase.com/docs/guides/auth/redirect-urls
SITE_URL=http://localhost:3000
ADDITIONAL_REDIRECT_URLS=
+
JWT_EXPIRY=3600
DISABLE_SIGNUP=false
-API_EXTERNAL_URL=http://localhost:8000
## Mailer Config
MAILER_URLPATHS_CONFIRMATION="/auth/v1/verify"
@@ -89,38 +145,55 @@ ENABLE_PHONE_AUTOCONFIRM=true
############
-# Studio - Configuration for the Dashboard
+# Storage - Configuration for Storage
############
-STUDIO_DEFAULT_ORGANIZATION=Default Organization
-STUDIO_DEFAULT_PROJECT=Default Project
+# Check the S3_PROTOCOL_ACCESS_KEY_ID/SECRET above, and
+# refer to the documentation at:
+# https://supabase.com/docs/guides/self-hosting/self-hosted-s3
+# to learn how to configure the S3 protocol endpoint
-# replace if you intend to use Studio outside of localhost
-SUPABASE_PUBLIC_URL=http://localhost:8000
+# S3 bucket when using S3 backend, directory name when using 'file'
+GLOBAL_S3_BUCKET=stub
-# Enable webp support
-IMGPROXY_ENABLE_WEBP_DETECTION=true
+# Used for S3 protocol endpoint configuration
+REGION=stub
-# Add your OpenAI API key to enable SQL Editor Assistant
-OPENAI_API_KEY=
+# Used by MinIO when added via:
+# docker compose -f docker-compose.yml -f docker-compose.s3.yml up -d
+MINIO_ROOT_USER=supa-storage
+MINIO_ROOT_PASSWORD=secret1234
+
+# Equivalent to project_ref as described here:
+# https://supabase.com/docs/guides/storage/s3/authentication#session-token
+STORAGE_TENANT_ID=stub
############
-# Functions - Configuration for Functions
+# Functions - Configuration for Edge functions
############
-# NOTE: VERIFY_JWT applies to all functions. Per-function VERIFY_JWT is not supported yet.
+
+# Documentation:
+# https://supabase.com/docs/guides/self-hosting/self-hosted-functions
+
+# NOTE: VERIFY_JWT applies to all functions
FUNCTIONS_VERIFY_JWT=false
############
-# Logs - Configuration for Analytics
-# Please refer to https://supabase.com/docs/reference/self-hosting-analytics/introduction
+# API - Configuration for PostgREST
############
-# Change vector.toml sinks to reflect this change
-# these cannot be the same value
-LOGFLARE_PUBLIC_ACCESS_TOKEN=your-super-secret-and-long-logflare-key-public
-LOGFLARE_PRIVATE_ACCESS_TOKEN=your-super-secret-and-long-logflare-key-private
+# Postgres schemas exposed via the REST API
+PGRST_DB_SCHEMAS=public,storage,graphql_public
+
+
+############
+# Analytics - Configuration for Logflare
+############
+
+# Check the LOGFLARE_* access token configuration above.
+# If Logflare is externally exposed, configure securely!
# Docker socket location - this value will differ depending on your OS
DOCKER_SOCKET_LOCATION=/var/run/docker.sock
@@ -129,16 +202,18 @@ DOCKER_SOCKET_LOCATION=/var/run/docker.sock
GOOGLE_PROJECT_ID=GOOGLE_PROJECT_ID
GOOGLE_PROJECT_NUMBER=GOOGLE_PROJECT_NUMBER
+
############
-# Storage - Configuration for the storage
+# API Proxy - Configuration for the Kong API gateway
############
-STORAGE_TENANT_ID=stub
-GLOBAL_S3_BUCKET=stub
-REGION=stub
-S3_PROTOCOL_ACCESS_KEY_ID=625729a08b95bf1b7ff351a663f3a23c
-S3_PROTOCOL_ACCESS_KEY_SECRET=850181e4652dd023b7a98c58ae0d2d34bd487ee0cc3254aed6eda37307425907
+KONG_HTTP_PORT=8000
+KONG_HTTPS_PORT=8443
-# Used in docker-compose.s3.yml for minio
-MINIO_ROOT_USER=supa-storage
-MINIO_ROOT_PASSWORD=secret1234
\ No newline at end of file
+
+############
+# imgproxy
+############
+
+# Enable webp support
+IMGPROXY_ENABLE_WEBP_DETECTION=true