chore(self-hosted): update proxy configs for envoy (#45229)

2026-05-06 08:56:46 -04:00 · 2026-04-27 15:22:02 +02:00
parent dfd3eec8e9
commit b4a6897b1b
9 changed files with 50 additions and 14 deletions
@@ -16,7 +16,7 @@ This URL:
 - Must be reachable from `auth` service
 - Must return a valid Golang HTML template

-To provide templates to Supabase Auth, you need a service that serves static HTML files. This can be any server of your choice. You can even use `kong` service which is included with the default Supabase docker configuration. The only requirement is that the `auth` service must be able to reach it via a HTTP GET request.
+To provide templates to Supabase Auth, you need a service that serves static HTML files. This can be any server of your choice. The only requirement is that the `auth` service must be able to reach it via a HTTP GET request.

 This guide uses [Caddy](https://github.com/caddyserver/caddy) for serving templates.

@@ -170,7 +170,7 @@ Review and change URL configuration variables:

  Throughout the self-hosting guides, `<your-domain>` stands for the host where your Supabase instance is reachable: your domain name, your server's IP, or `localhost`, depending on your setup.

-  - **Default setup:** Kong listens on port `8000`, so the full URL is `http://<your-domain>:8000`.
+  - **Default setup:** The API gateway (Kong) listens on port `8000`, so the full URL is `http://<your-domain>:8000`.
  - **Behind a [reverse proxy](/docs/guides/self-hosting/self-hosted-proxy-https):** the proxy terminates TLS on port `443`, so the URL becomes `https://<your-domain>`.

 </Admonition>
@@ -291,7 +291,7 @@ Each of the APIs is available through the same API gateway:

 ## 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.
+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 the API gateway.

 See the [Configure HTTPS](/docs/guides/self-hosting/self-hosted-proxy-https) guide for detailed setup instructions.

@@ -351,7 +351,7 @@ Supabase is built from open source tools, each chosen or developed for productio
 If the tools and communities already exist, with an MIT, Apache 2, PostgreSQL, 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.

 <Image
-  alt="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."
+  alt="Diagram showing the architecture of Supabase. The API gateway (Kong) 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."
  src={{
    dark: "/docs/img/supabase-architecture.svg",
    light: "/docs/img/supabase-architecture--light.svg",
@@ -127,7 +127,7 @@ New variables default to empty values in `.env.example`. When empty, the API gat

 The new authentication configuration is fully backward compatible:

- **Kong accepts both key types simultaneously.** You can migrate clients incrementally - some using legacy API keys, others using the new ones.
+- **The API Gateway accepts both key types simultaneously.** You can migrate clients incrementally - some using legacy API keys, others using the new ones.
 - **JWKS includes the symmetric key.** `JWT_JWKS` contains both the EC public key (for verifying new ES256 tokens) and the legacy `JWT_SECRET` as a symmetric JWK (for verifying old HS256 tokens). Services that receive `JWT_JWKS` can verify both token types.
 - **No database changes required.** The asymmetric key system operates entirely at the API gateway and service configuration layer.

@@ -192,7 +192,7 @@ For **Realtime WebSocket** connections, the API key is sent as a `?apikey=` quer

 **Storage** and **Edge Functions** accept requests without an API key. These services handle their own authentication.

-### API gateway routing
+### Kong API gateway routing

 Kong is configured with two consumers that each accept both the legacy and new API keys:

@@ -32,7 +32,7 @@ You will have to register this URL with each OAuth provider.
 When a user signs in with an OAuth provider, the following flow occurs:

 1. Your app calls `supabase.auth.signInWithOAuth()` and the browser redirects to the Auth service
-2. API gateway (Kong) routes the request to the Auth container (`/auth/v1/authorize`)
+2. The API gateway routes the request to the Auth container (`/auth/v1/authorize`)
 3. Auth redirects the user to the OAuth provider (e.g., Google) for consent
 4. The provider redirects back to `https://<your-domain>/auth/v1/callback`
 5. Auth exchanges the authorization code for tokens and redirects the user to your `SITE_URL` or an allowed redirect URL
@@ -16,21 +16,27 @@ You need:

 ## Set up HTTPS

-Below are two options for adding a reverse proxy with automatic HTTPS in front of your self-hosted Supabase: **Caddy** (simpler, zero-config TLS) and **Nginx + Let's Encrypt** (more control over proxy settings). Both sit in front of Kong and terminate TLS, so internal traffic stays on HTTP.
+Below are two options for adding a reverse proxy with automatic HTTPS in front of your self-hosted Supabase: **Caddy** (simpler, zero-config TLS) and **Nginx + Let's Encrypt** (more control over proxy settings). Both sit in front of the API gateway and terminate TLS, so internal traffic stays on HTTP.

 <Admonition type="tip" label="Using a different reverse proxy?">

 If you already run [HAProxy](https://www.haproxy.com/), [Traefik](https://traefik.io/), [Nginx Proxy Manager](https://nginxproxymanager.com/), or another reverse proxy for your infrastructure, you can use it instead of Caddy or Nginx above. The key requirements are:

- Proxy to Kong on port `8000` (or `<your-ip>:8000` if the proxy runs outside the Docker network)
+- Proxy to the API gateway on port `8000` (or `<your-ip>:8000` if the proxy runs outside the Docker network)
 - Enable WebSocket support (required for Realtime)
 - Add `X-Forwarded` headers to all requests
- Comment out Kong's host port bindings in `docker-compose.yml` if the proxy runs in the same Docker network
+- Comment out the API gateway's host port bindings in `docker-compose.yml` if the proxy runs in the same Docker network
 - Update `SUPABASE_PUBLIC_URL`, `API_EXTERNAL_URL`, and `SITE_URL` in `.env` to your HTTPS URL
 - See `volumes/proxy` for example proxy configuration files

 </Admonition>

+<Admonition type="note" label="Using Envoy instead of Kong?">
+
+Envoy is an optional [API gateway](/docs/guides/self-hosting/self-hosted-envoy), enabled via the `docker-compose.envoy.yml` overlay. If you already run Envoy instead of Kong, edit `docker-compose.caddy.yml` or `docker-compose.nginx.yml` to comment out the `kong:` block and uncomment the `api-gw:` block (and the matching `depends_on` entry) so the reverse proxy sits in front of Envoy.
+
+</Admonition>
+
 ### Step 1: Update environment variables

 Update the URL configuration in your `.env` file to use your HTTPS domain:
@@ -110,7 +116,7 @@ Self-signed certificates trigger browser warnings and are rejected by most OAuth

 </Admonition>

-For development or internal networks where you cannot use Let's Encrypt, you can configure Kong to serve HTTPS directly using self-signed certificates.
+For development or internal networks where you cannot use Let's Encrypt, here's how you can configure Kong (the current default API gateway) to serve HTTPS directly using self-signed certificates.

 ### Step 1: Generate a self-signed certificate

@@ -190,7 +196,7 @@ If Caddy or Certbot fails to obtain a certificate:

 If Realtime subscriptions fail to connect:

- **Caddy** handles WebSocket upgrades automatically - check that Kong is healthy
+- **Caddy** handles WebSocket upgrades automatically - check that the API gateway is healthy
 - **Nginx** requires explicit `Upgrade` and `Connection` headers on the `/realtime/v1/` location. Verify your `nginx.conf` includes these headers as shown above

 ### OAuth callback URL mismatch
@@ -195,7 +195,7 @@ const client = new S3Client({

 S3 clients sign requests using the access key ID and secret. If you see `SignatureDoesNotMatch`, verify that the `REGION`, `S3_PROTOCOL_ACCESS_KEY_ID` and `S3_PROTOCOL_ACCESS_KEY_SECRET` in your `.env` file match what your S3 client is using.

-**If you use a custom reverse proxy**: with the [new API keys and auth](/docs/guides/self-hosting/self-hosted-auth-keys) configuration, requests to Storage should be forwarded to the API gateway (Kong) for proper handling. If you are still using legacy API keys and proxy directly to Storage, make sure your proxy sets the `X-Forwarded-Prefix` header to `/storage/v1` so that signed URLs are generated correctly. In both cases, `STORAGE_PUBLIC_URL` must be [set properly](https://github.com/supabase/supabase/blob/a5f4a59e0e262394b345600e8d8a2241d6ac3b64/docker/docker-compose.yml#L369) in `docker-compose.yml`.
+**If you use a custom reverse proxy**: with the [new API keys and auth](/docs/guides/self-hosting/self-hosted-auth-keys) configuration, requests to Storage should be forwarded to the API gateway for proper handling. If you are still using legacy API keys and proxy directly to Storage, make sure your proxy sets the `X-Forwarded-Prefix` header to `/storage/v1` so that signed URLs are generated correctly. In both cases, `STORAGE_PUBLIC_URL` must be [set properly](https://github.com/supabase/supabase/blob/a5f4a59e0e262394b345600e8d8a2241d6ac3b64/docker/docker-compose.yml#L369) in `docker-compose.yml`.

 ### TUS upload errors on Cloudflare R2

@@ -561,7 +561,7 @@ base64 -w 0 -i pk_rsa1.der
 ### IdP cannot reach the ACS endpoint

 - Verify `API_EXTERNAL_URL` is set to a URL the IdP can reach (not `localhost` unless testing locally)
- Check that the Kong routes for `/sso/saml/acs` and `/sso/saml/metadata` are configured as open (no `key-auth` plugin).
+- Check that the API gateway routes for `/sso/saml/acs` and `/sso/saml/metadata` are configured as open (no `key-auth` plugin).
 - Check the Auth container logs: `docker compose logs auth`

 ### "No SSO provider found for this domain"
@@ -1,5 +1,18 @@
 services:

+  # By default, Kong is used as the API gateway and its ports/env are reset
+  # below so Caddy can terminate TLS in front of it.
+  #
+  # When running Envoy instead, e.g.:
+  #   docker compose -f docker-compose.yml -f docker-compose.envoy.yml \
+  #                  -f docker-compose.caddy.yml up -d
+  # comment out the `kong:` block below and uncomment the `api-gw:` block
+  # (and the matching `depends_on` entry further down) so Caddy sits in front
+  # of Envoy rather than Kong.
+
+  #api-gw:
+  #  ports: !reset []
+
  kong:
    ports: !reset []
    environment:
@@ -14,6 +27,8 @@ services:
      - "443:443"
      - "443:443/udp"
    depends_on:
+      #api-gw:
+      #  condition: service_healthy
      kong:
        condition: service_healthy
      studio:
@@ -1,5 +1,18 @@
 services:

+  # By default, Kong is used as the API gateway and its ports/env are reset
+  # below so nginx can terminate TLS in front of it.
+  #
+  # When running Envoy instead, e.g.:
+  #   docker compose -f docker-compose.yml -f docker-compose.envoy.yml \
+  #                  -f docker-compose.nginx.yml up -d
+  # comment out the `kong:` block below and uncomment the `api-gw:` block
+  # (and the matching `depends_on` entry further down) so nginx sits in front
+  # of Envoy rather than Kong.
+
+  #api-gw:
+  #  ports: !reset []
+
  kong:
    ports: !reset []
    environment:
@@ -13,6 +26,8 @@ services:
      - "80:80"
      - "443:443"
    depends_on:
+      #api-gw:
+      #  condition: service_healthy
      kong:
        condition: service_healthy
      studio: