add https proxy how-to for self-hosted by aantti · Pull Request #43293

add https proxy how-to for self-hosted by aantti · Pull Request #43293 · supabase/supabase

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment, Open in v0	Mar 2, 2026 10:16pm

8 Skipped Deployments

Project	Deployment	Updated (UTC)
cms	Ignored	Mar 2, 2026 10:16pm
studio	Ignored	Mar 2, 2026 10:16pm
design-system	Skipped	Mar 2, 2026 10:16pm
learn	Skipped	Mar 2, 2026 10:16pm
studio-self-hosted	Skipped	Mar 2, 2026 10:16pm
studio-staging	Skipped	Mar 2, 2026 10:16pm
ui-library	Skipped	Mar 2, 2026 10:16pm
zone-www-dot-com	Skipped	Mar 2, 2026 10:16pm

This pull request has been ignored for the connected project xguihxuzqibwxjnimxev because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Central YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Cache: Disabled due to Reviews > Disable Cache setting

Disabled knowledge base sources:

Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 55c896d and 15de47c.

📒 Files selected for processing (1)

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

🚧 Files skipped from review as they are similar to previous changes (1)

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

📝 Walkthrough

Summary by CodeRabbit

Documentation
- Added a comprehensive guide for configuring a reverse proxy with HTTPS for self-hosted deployments (Caddy and Nginx options), including prerequisites, setup, verification, troubleshooting, and dev self-signed certificate guidance
- Updated self-hosting Docker docs to highlight HTTPS requirements and link to the new guide
Content / Navigation
- Added a new "Add Reverse Proxy with HTTPS" entry under How-to Guides for easier discoverability
Chores
- Minor doc comment clarifications in example env and compose files

Walkthrough

This pull request adds documentation and configuration guidance for setting up HTTPS with a reverse proxy in self-hosted Supabase deployments. A new navigation menu item references a comprehensive guide file covering reverse proxy setup with Caddy or Nginx, TLS certificate configuration, and troubleshooting. An existing self-hosting Docker guide now includes a section directing users to the dedicated HTTPS configuration documentation. Docker Compose configuration lines for SSL certificates are commented out to reflect the reverse proxy approach. The .env.example file receives a minor comment text update.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

rdjsonl

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

- [docker-nginx-certbot on GitHub](https://github.com/JonasAlfredsson/docker-nginx-certbot)

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: certbot (configure rule at supa-mdx-lint/Rule003Spelling.toml)

- [docker-nginx-certbot on GitHub](https://github.com/JonasAlfredsson/docker-nginx-certbot)


		#### 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		#### 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		## 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		## 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

…pabase into self-hosted/docs-proxy-https


		<Admonition type="tip">

		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:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: HAProxy (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		<Admonition type="tip">

		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:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Traefik (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		<Admonition type="tip">

		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:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		<Admonition type="tip">

		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:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		<Admonition type="tip">

		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:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

		docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d
		```

		Caddy configuration is in `volumes/proxy/caddy/Caddyfile`.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)

		</TabPanel>
		<TabPanel id="nginx" label="Nginx + Let's Encrypt">

		This option uses a 3rd party Nginx Docker image ([`jonasal/nginx-certbot`](https://github.com/JonasAlfredsson/docker-nginx-certbot)), which includes Certbot for automatic Let's Encrypt certificate issuance and renewal in a single container.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

		</TabPanel>
		<TabPanel id="nginx" label="Nginx + Let's Encrypt">

		This option uses a 3rd party Nginx Docker image ([`jonasal/nginx-certbot`](https://github.com/JonasAlfredsson/docker-nginx-certbot)), which includes Certbot for automatic Let's Encrypt certificate issuance and renewal in a single container.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Certbot (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		This option uses a 3rd party Nginx Docker image ([`jonasal/nginx-certbot`](https://github.com/JonasAlfredsson/docker-nginx-certbot)), which includes Certbot for automatic Let's Encrypt certificate issuance and renewal in a single container.

		Start Nginx by using the pre-configured `docker-compose.nginx.yml` overlay:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

		docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
		```

		Nginx configuration template is in `volumes/proxy/nginx/supabase-nginx.conf.tpl`. On container startup, `${NGINX_SERVER_NAME}` is substituted using the environment variable from the `.env` file. The [`jonasal/nginx-certbot`](https://github.com/JonasAlfredsson/docker-nginx-certbot) image reads the resolved `server_name` to determine which domain to request a Let's Encrypt certificate for.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

Hi team,

I'll add the HTTPS proxy how-to for self-hosted setup. Documentation improvement!

Let me know if I can proceed!

aantti marked this pull request as ready for review

March 2, 2026 18:09

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx`:
- Around line 19-23: The spelling linter is flagging product names (Caddy,
Nginx, Certbot, HAProxy, Traefik); fix by adding these terms to the spelling
dictionary file supa-mdx-lint/Rule003Spelling.toml so they are accepted
globally, or alternatively add an inline suppressor {/*
supa-mdx-lint-disable-next-line Rule003Spelling */} immediately before the
affected lines in the MDX (use the dictionary change as the preferred long-term
fix).

ℹ️ Review info

Configuration used: Central YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Cache: Disabled due to Reviews > Disable Cache setting

Disabled knowledge base sources:

Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between f5667ac and 6ef4bf7.

📒 Files selected for processing (5)

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
apps/docs/content/guides/self-hosting/docker.mdx
apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx
docker/.env.example
docker/docker-compose.yml

Comment on lines +19 to +23

		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.

		<Admonition type="tip">

		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:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add product names to spelling dictionary to pass CI.

The docs_lint pipeline is failing because product names (Caddy, Nginx, Certbot, HAProxy, Traefik) are not in the spelling dictionary. Either:

Add these terms to supa-mdx-lint/Rule003Spelling.toml, or
Use inline lint-disable comments like {/* supa-mdx-lint-disable-next-line Rule003Spelling */} before affected lines (as done elsewhere in the codebase, e.g., lines 135, 184 in docker.mdx)

Option 1 is preferred since these are common infrastructure product names used throughout documentation.

🧰 Tools

🪛 GitHub Actions: docs_lint

[error] 19-19: [Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)

[error] 19-19: [Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

[error] 23-23: [Rule003Spelling] Word not found in dictionary: HAProxy (configure rule at supa-mdx-lint/Rule003Spelling.toml)

[error] 23-23: [Rule003Spelling] Word not found in dictionary: Traefik (configure rule at supa-mdx-lint/Rule003Spelling.toml)

[error] 23-23: [Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

[error] 23-23: [Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)

[error] 23-23: [Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx` around
lines 19 - 23, The spelling linter is flagging product names (Caddy, Nginx,
Certbot, HAProxy, Traefik); fix by adding these terms to the spelling dictionary
file supa-mdx-lint/Rule003Spelling.toml so they are accepted globally, or
alternatively add an inline suppressor {/* supa-mdx-lint-disable-next-line
Rule003Spelling */} immediately before the affected lines in the MDX (use the
dictionary change as the preferred long-term fix).

…pabase into self-hosted/docs-proxy-https

		# - ${KONG_HTTP_PORT}:8000/tcp
		```

		Uncomment the certificate volume mounts and SSL environment variables in `docker-compose.yml`:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Uncomment (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		### Certificate not issued

		If Caddy or Certbot fails to obtain a certificate:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		### Certificate not issued

		If Caddy or Certbot fails to obtain a certificate:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Certbot (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		If Realtime subscriptions fail to connect:

		- Caddy handles WebSocket upgrades automatically - check that Kong is healthy

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)

		If Realtime subscriptions fail to connect:

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		### ERR_CERT_AUTHORITY_INVALID

		This is expected when using self-signed certificates. For production, use Caddy or Nginx with Let's Encrypt. If you need to use self-signed certificates, add the certificate to your system's trust store or use a browser flag to bypass the warning.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		## Additional resources

		- [Caddy documentation](https://caddyserver.com/docs/)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Caddy (configure rule at supa-mdx-lint/Rule003Spelling.toml)

		## Additional resources

		- [Caddy documentation](https://caddyserver.com/docs/)
		- [Nginx documentation](https://nginx.org/en/docs/) (on nginx.org)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: Nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		- [Caddy documentation](https://caddyserver.com/docs/)
		- [Nginx documentation](https://nginx.org/en/docs/) (on nginx.org)
		- [docker-nginx-certbot on GitHub](https://github.com/JonasAlfredsson/docker-nginx-certbot)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: nginx (configure rule at supa-mdx-lint/Rule003Spelling.toml)


		- [Caddy documentation](https://caddyserver.com/docs/)
		- [Nginx documentation](https://nginx.org/en/docs/) (on nginx.org)
		- [docker-nginx-certbot on GitHub](https://github.com/JonasAlfredsson/docker-nginx-certbot)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [rdjsonl] _{reported by reviewdog 🐶}
[Rule003Spelling] Word not found in dictionary: certbot (configure rule at supa-mdx-lint/Rule003Spelling.toml)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx`:
- Around line 128-133: The private key file created by the openssl command
(server.key from the openssl req block) is being made world-readable with chmod
644; change the permission operation to set owner-only access (e.g., chmod 600
or chmod 400) after the openssl command so server.key is not world-readable;
update the chmod call that references volumes/api/server.key accordingly.

ℹ️ Review info

Configuration used: Central YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Cache: Disabled due to Reviews > Disable Cache setting

Disabled knowledge base sources:

Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 6ef4bf7 and 55c896d.

📒 Files selected for processing (1)

apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx

Comment on lines +128 to +133

		openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
		-keyout volumes/api/server.key \
		-out volumes/api/server.crt \
		-subj "/CN=<your-domain>" && \
		chmod 644 volumes/api/server.key
		```

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Private key permissions are too permissive in the self-signed example.

Line 132 uses chmod 644 for server.key, which makes the private key world-readable on the host. Use owner-only permissions.

🔒 Suggested fix

-  chmod 644 volumes/api/server.key
+  chmod 600 volumes/api/server.key

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/docs/content/guides/self-hosting/self-hosted-proxy-https.mdx` around
lines 128 - 133, The private key file created by the openssl command (server.key
from the openssl req block) is being made world-readable with chmod 644; change
the permission operation to set owner-only access (e.g., chmod 600 or chmod 400)
after the openssl command so server.key is not world-readable; update the chmod
call that references volumes/api/server.key accordingly.