Refactor reverse proxy docs to tutorials

- Relocate Apache, Caddy, and NGINX reverse proxy setup docs. - Remove embedded config examples, referencing tutorials instead. - Streamline tutorials for easier setup guidance.
coder · matifali · Oct 10, 2024 · Oct 9, 2024 · Oct 9, 2024 · Oct 10, 2024
commit cbd75a3da0341cc8f27487415ab261cebed0ca9f
diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md
@@ -61,9 +61,9 @@ The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
 accompanying configuration flags. However, Coder can also run behind a
 reverse-proxy to terminate TLS certificates from LetsEncrypt.
 
-- [Apache](./reverse-proxy/apache/index.md)
-- [Caddy](./reverse-proxy/caddy/index.md)
-- [NGINX](./reverse-proxy/nginx/index.md)
+- [Apache](../../tutorials/reverse-proxy-apache.md)
+- [Caddy](../../tutorials/reverse-proxy-caddy.md)
+- [NGINX](../../tutorials/reverse-proxy-nginx.md)
 
 ### Kubernetes TLS configuration
 

diff --git a/docs/admin/setup/reverse-proxy/apache/coder.conf b/docs/admin/setup/reverse-proxy/apache/coder.conf
diff --git a/docs/admin/setup/reverse-proxy/caddy/Caddyfile b/docs/admin/setup/reverse-proxy/caddy/Caddyfile
diff --git a/docs/admin/setup/reverse-proxy/caddy/docker-compose.yaml b/docs/admin/setup/reverse-proxy/caddy/docker-compose.yaml
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -201,28 +201,6 @@
 							"title": "Telemetry",
 							"description": "Learn what usage telemetry Coder collects",
 							"path": "./admin/setup/telemetry.md"
-						},
-						{
-							"title": "Reverse Proxy",
-							"description": "Learn how to host Coder behind a reverse proxy",
-							"path": "./admin/setup/reverse-proxy/index.md",
-							"children": [
-								{
-									"title": "Apache",
-									"description": "Learn how to configure Coder to use Apache as a reverse proxy",
-									"path": "./admin/setup/reverse-proxy/apache/index.md"
-								},
-								{
-									"title": "Caddy",
-									"description": "Learn how to configure Coder to use Caddy as a reverse proxy",
-									"path": "./admin/setup/reverse-proxy/caddy/index.md"
-								},
-								{
-									"title": "NGINX",
-									"description": "Learn how to configure Coder to use NGINX as a reverse proxy",
-									"path": "./admin/setup/reverse-proxy/nginx/index.md"
-								}
-							]
 						}
 					]
 				},
@@ -721,6 +699,21 @@
 					"description": "Learn how to clone Git repositories in Coder",
 					"path": "./tutorials/cloning-git-repositories.md"
 				},
+				{
+					"title": "Use Apache as a Reverse Proxy",
+					"description": "Learn how to use Apache as a reverse proxy",
+					"path": "./tutorials/reverse-proxy-apache.md"
+				},
+				{
+					"title": "Use Caddy as a Reverse Proxy",
+					"description": "Learn how to use Caddy as a reverse proxy",
+					"path": "./tutorials/reverse-proxy-caddy.md"
+				},
+				{
+					"title": "Use NGINX as a Reverse Proxy",
+					"description": "Learn how to use NGINX as a reverse proxy",
+					"path": "./tutorials/reverse-proxy-nginx.md"
+				},
 				{
 					"title": "FAQs",
 					"description": "Miscellaneous FAQs from our community",

diff --git a/...admin/setup/reverse-proxy/apache/index.md → docs/tutorials/reverse-proxy-apache.md b/...admin/setup/reverse-proxy/apache/index.md → docs/tutorials/reverse-proxy-apache.md
@@ -3,7 +3,7 @@
 ## Requirements
 
 1. Start a Coder deployment and be sure to set the following
-   [configuration values](../../index.md):
+   [configuration values](../admin/setup/index.md):
 
    ```env
    CODER_HTTP_ADDRESS=127.0.0.1:3000

diff --git a/.../admin/setup/reverse-proxy/caddy/index.md → docs/tutorials/reverse-proxy-caddy.md b/.../admin/setup/reverse-proxy/caddy/index.md → docs/tutorials/reverse-proxy-caddy.md
@@ -11,34 +11,101 @@ certificates, you'll need a domain name that resolves to your Caddy server.
 1. [Install Docker](https://docs.docker.com/engine/install/) and
    [Docker Compose](https://docs.docker.com/compose/install/)
 
-1. Start with our
-   [example configuration](https://github.com/coder/coder/blob/main/docs/admin/setup/reverse-proxy/caddy/docker-compose.yaml)
+2. Create a `docker-compose.yaml` file and add the following:
+
+   ```yaml
+   services:
+   coder:
+   	image: ghcr.io/coder/coder:${CODER_VERSION:-latest}
+   	environment:
+   		CODER_PG_CONNECTION_URL: "postgresql://${POSTGRES_USER:-username}:${POSTGRES_PASSWORD:-password}@database/${POSTGRES_DB:-coder}?sslmode=disable"
+   		CODER_HTTP_ADDRESS: "0.0.0.0:7080"
+   		# You'll need to set CODER_ACCESS_URL to an IP or domain
+   		# that workspaces can reach. This cannot be localhost
+   		# or 127.0.0.1 for non-Docker templates!
+   		CODER_ACCESS_URL: "${CODER_ACCESS_URL}"
+   		# Optional) Enable wildcard apps/dashboard port forwarding
+   		CODER_WILDCARD_ACCESS_URL: "${CODER_WILDCARD_ACCESS_URL}"
+   		# If the coder user does not have write permissions on
+   		# the docker socket, you can uncomment the following
+   		# lines and set the group ID to one that has write
+   		# permissions on the docker socket.
+   		#group_add:
+   		#  - "998" # docker group on host
+   	volumes:
+   		- /var/run/docker.sock:/var/run/docker.sock
+   	depends_on:
+   		database:
+   		condition: service_healthy
+
+   database:
+   	image: "postgres:16"
+   	ports:
+   		- "5432:5432"
+   	environment:
+   		POSTGRES_USER: ${POSTGRES_USER:-username} # The PostgreSQL user (useful to connect to the database)
+   		POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password} # The PostgreSQL password (useful to connect to the database)
+   		POSTGRES_DB: ${POSTGRES_DB:-coder} # The PostgreSQL default database (automatically created at first launch)
+   	volumes:
+   		- coder_data:/var/lib/postgresql/data # Use "docker volume rm coder_coder_data" to reset Coder
+   	healthcheck:
+   		test:
+   		[
+   			"CMD-SHELL",
+   			"pg_isready -U ${POSTGRES_USER:-username} -d ${POSTGRES_DB:-coder}",
+   		]
+   		interval: 5s
+   		timeout: 5s
+   		retries: 5
+
+   caddy:
+   	image: caddy:2.6.2
+   	ports:
+   		- "80:80"
+   		- "443:443"
+   		- "443:443/udp"
+   	volumes:
+   		- $PWD/Caddyfile:/etc/caddy/Caddyfile
+   		- caddy_data:/data
+   		- caddy_config:/config
+
+   volumes:
+   	coder_data:
+   	caddy_data:
+   	caddy_config:
+   ```
 
-   ```shell
-   # Create a project folder
-   cd $HOME
-   mkdir coder-with-caddy
-   cd coder-with-caddy
-
-   # Clone coder/coder and copy the Caddy example
-   git clone https://github.com/coder/coder /tmp/coder
-   mv /tmp/coder/docs/admin/setup/web-server/caddy $(pwd)
+3. Create a `Caddyfile` and add the following:
+
+   ```
+   {
+   	on_demand_tls {
+   		ask http://example.com
+   	}
+   }
+
+   coder.example.com, *.coder.example.com {
+     reverse_proxy coder:7080
+     tls {
+       	on_demand
+         issuer acme {
+            email email@example.com
+         }
+     	}
+   }
    ```
 
-1. Modify the
-   [Caddyfile](https://github.com/coder/coder/blob/main/docs/admin/setup/reverse-proxy/caddy/Caddyfile)
-   and change the following values:
+   Here;
 
-   - `localhost:3000`: Change to `coder:7080` (Coder container on Docker
-     network)
+   - `coder:7080` is the address of the Coder container on the Docker network.
+   - `coder.example.com` is the domain name you're using for Coder.
+   - `*.coder.example.com` is the domain name for wildcard apps, commonly used
+     for [dashboard port forwarding](../admin/networking/port-forwarding.md).
+     This is optional and can be removed.
    - `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
      (does not have to be Coder admin email)
-   - `coder.example.com`: Domain name you're using for Coder.
-   - `*.coder.example.com`: Domain name for wildcard apps, commonly used for
-     [dashboard port forwarding](../../../networking/port-forwarding.md). This
-     is optional and can be removed.
 
-1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the
+4. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the
    domain you're using in your Caddyfile.
 
    ```shell
@@ -62,14 +129,14 @@ certificates, you'll need a domain name that resolves to your Caddy server.
      (does not have to be Coder admin email)
    - `coder.example.com`: Domain name you're using for Coder.
    - `*.coder.example.com`: Domain name for wildcard apps, commonly used for
-     [dashboard port forwarding](../../../networking/port-forwarding.md). This
+     [dashboard port forwarding](../admin/networking/port-forwarding.md). This
      is optional and can be removed.
    - `localhost:3000`: Address Coder is running on. Modify this if you changed
      `CODER_HTTP_ADDRESS` in the Coder configuration.
    - _DO NOT CHANGE the `ask http://example.com` line! Doing so will result in
      your certs potentially not being generated._
 
-4. [Configure Coder](../../index.md) and change the following values:
+4. [Configure Coder](../admin/setup/index.md) and change the following values:
 
    - `CODER_ACCESS_URL`: root domain (e.g. `https://coder.example.com`)
    - `CODER_WILDCARD_ACCESS_URL`: wildcard domain (e.g. `*.example.com`).
@@ -119,7 +186,7 @@ By default, this configuration uses Caddy's
 [on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to
 generate a certificate for each subdomain (e.g. `app1.coder.example.com`,
 `app2.coder.example.com`). When users visit new subdomains, such as accessing
-[ports on a workspace](../../../networking/port-forwarding.md), the request will
+[ports on a workspace](../admin/networking/port-forwarding.md), the request will
 take an additional 5-30 seconds since a new certificate is being generated.
 
 For production deployments, we recommend configuring Caddy to generate a

diff --git a/.../admin/setup/reverse-proxy/nginx/index.md → docs/tutorials/reverse-proxy-nginx.md b/.../admin/setup/reverse-proxy/nginx/index.md → docs/tutorials/reverse-proxy-nginx.md
@@ -3,7 +3,7 @@
 ## Requirements
 
 1. Start a Coder deployment and be sure to set the following
-   [configuration values](../../index.md):
+   [configuration values](../admin/setup/index.md):
 
    ```env
    CODER_HTTP_ADDRESS=127.0.0.1:3000