From 3330da2a8bcb18d0e66a058a940387fadf952b8a Mon Sep 17 00:00:00 2001
From: Roy Anger <roy@clerk.dev>
Date: Fri, 20 Dec 2024 20:53:44 -0500
Subject: [PATCH] feat: Added doc for for web server deployment (#1813)

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
---
 docs/deployments/deploy-behind-a-proxy.mdx | 54 ++++++++++++++++++++++
 docs/manifest.json                         |  4 ++
 2 files changed, 58 insertions(+)
 create mode 100644 docs/deployments/deploy-behind-a-proxy.mdx

diff --git a/docs/deployments/deploy-behind-a-proxy.mdx b/docs/deployments/deploy-behind-a-proxy.mdx
new file mode 100644
index 0000000000..d35e1ccd49
--- /dev/null
+++ b/docs/deployments/deploy-behind-a-proxy.mdx
@@ -0,0 +1,54 @@
+---
+title: Deploy a Clerk app behind a proxy
+description: Learn how to deploy a Clerk app to a web server using proxies and reverse proxies like nginx or Caddy, or using Docker.
+---
+
+When deploying a Clerk app behind a proxy, you must forward two headers:
+
+- `X-Forwarded-Host` - The host of the request.
+- `X-Forwarded-Proto` - The protocol of the request.
+
+Here are some common platforms and servers that require header proxying:
+
+- [nginx](https://nginx.org/en/)
+- [Caddy](https://caddyserver.com/)
+- [Docker](https://www.docker.com/)
+- [AWS Amplify](https://amplify.com/)
+
+## `nginx` configuration example
+
+The following can be added to your `nginx` configuration to forward the headers to your application.
+
+```nginx
+proxy_set_header X-Forwarded-Host $host;
+proxy_set_header X-Forwarded-Proto https;
+```
+
+## Test header forwarding
+
+To test if the headers are forwarded correctly, you can console log them to check what their values are. They are available on the `request` object.
+
+```ts {{ filename: 'middleware.ts' }}
+export default clerkMiddleware(
+  (auth, req) => {
+    console.log('=========================')
+    console.log('Request Headers')
+    console.log('x-forwarded-host', req.headers.get('x-forwarded-host'))
+    console.log('x-forwarded-proto', req.headers.get('x-forwarded-proto'))
+    console.log('=========================')
+  },
+  { debug: debugStatus },
+)
+```
+
+The `X-Forwarded-Host` header should return the same domain as the one you configured on the [**Domains**](https://dashboard.clerk.com/last-active?path=domains) page in the Clerk Dashboard. The `X-Forwarded-Proto` header should return `https` as Clerk requires this value to be `https` for production instances.
+
+Here is an example result:
+
+```log
+=========================
+Request Headers
+x-forwarded-host example.com
+x-forwarded-proto https
+=========================
+```
diff --git a/docs/manifest.json b/docs/manifest.json
index 92fbb2622b..7b2ce79b51 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1428,6 +1428,10 @@
                           "title": "Deploy to Vercel",
                           "href": "/docs/deployments/deploy-to-vercel"
                         },
+                        {
+                          "title": "Deploy behind a proxy",
+                          "href": "/docs/deployments/deploy-behind-a-proxy"
+                        },
                         {
                           "title": "Set up a staging environment",
                           "href": "/docs/deployments/set-up-staging"