diff --git a/apps/docs/content/guides/self-hosting/custom-email-templates.mdx b/apps/docs/content/guides/self-hosting/custom-email-templates.mdx index 777933cf4a..090dfc390c 100644 --- a/apps/docs/content/guides/self-hosting/custom-email-templates.mdx +++ b/apps/docs/content/guides/self-hosting/custom-email-templates.mdx @@ -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. diff --git a/apps/docs/content/guides/self-hosting/docker.mdx b/apps/docs/content/guides/self-hosting/docker.mdx index 531c8ffd53..d6ee98a7de 100644 --- a/apps/docs/content/guides/self-hosting/docker.mdx +++ b/apps/docs/content/guides/self-hosting/docker.mdx @@ -170,7 +170,7 @@ Review and change URL configuration variables: Throughout the self-hosting guides, `` 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://:8000`. + - **Default setup:** The API gateway (Kong) listens on port `8000`, so the full URL is `http://: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://`. @@ -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. 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./auth/v1/callback` 5. Auth exchanges the authorization code for tokens and redirects the user to your `SITE_URL` or an allowed redirect URL diff --git a/apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx b/apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx index 2b492bcd88..794a233cec 100644 --- a/apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx +++ b/apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx @@ -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. 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 `:8000` if the proxy runs outside the Docker network) +- Proxy to the API gateway on port `8000` (or `: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 + + +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. + + + ### 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 -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 diff --git a/apps/docs/content/guides/self-hosting/self-hosted-s3.mdx b/apps/docs/content/guides/self-hosting/self-hosted-s3.mdx index 8b3aa99890..b7614d6781 100644 --- a/apps/docs/content/guides/self-hosting/self-hosted-s3.mdx +++ b/apps/docs/content/guides/self-hosting/self-hosted-s3.mdx @@ -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 diff --git a/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx b/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx index 1d76bf833e..ec2d8b0e32 100644 --- a/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx +++ b/apps/docs/content/guides/self-hosting/self-hosted-saml-sso.mdx @@ -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" diff --git a/docker/docker-compose.caddy.yml b/docker/docker-compose.caddy.yml index 3f12d3bf20..35510081e5 100644 --- a/docker/docker-compose.caddy.yml +++ b/docker/docker-compose.caddy.yml @@ -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: diff --git a/docker/docker-compose.nginx.yml b/docker/docker-compose.nginx.yml index 81d604b36a..70afee623b 100644 --- a/docker/docker-compose.nginx.yml +++ b/docker/docker-compose.nginx.yml @@ -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: