diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index 23d28ffb52..527c33adc3 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -61,6 +61,10 @@ 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](../../tutorials/reverse-proxy-apache.md) +- [Caddy](../../tutorials/reverse-proxy-caddy.md) +- [NGINX](../../tutorials/reverse-proxy-nginx.md) + ### Kubernetes TLS configuration Below are the steps to configure Coder to terminate TLS when running on diff --git a/docs/admin/setup/web-server/apache/coder.conf b/docs/admin/setup/web-server/apache/coder.conf deleted file mode 100644 index ebbd68c11b..0000000000 --- a/docs/admin/setup/web-server/apache/coder.conf +++ /dev/null @@ -1,28 +0,0 @@ - # Redirect HTTP to HTTPS - - ServerName coder.example.com - ServerAlias *.coder.example.com - Redirect permanent / https://coder.example.com/ - - - - ServerName coder.example.com - ServerAlias *.coder.example.com - ErrorLog ${APACHE_LOG_DIR}/error.log - CustomLog ${APACHE_LOG_DIR}/access.log combined - - ProxyPass / http://127.0.0.1:3000/ upgrade=any # required for websockets - ProxyPassReverse / http://127.0.0.1:3000/ - ProxyRequests Off - ProxyPreserveHost On - - RewriteEngine On - # Websockets are required for workspace connectivity - RewriteCond %{HTTP:Connection} Upgrade [NC] - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L] - - SSLCertificateFile /etc/letsencrypt/live/coder.example.com/fullchain.pem - SSLCertificateKeyFile /etc/letsencrypt/live/coder.example.com/privkey.pem - - diff --git a/docs/admin/setup/web-server/caddy/Caddyfile b/docs/admin/setup/web-server/caddy/Caddyfile deleted file mode 100644 index 67b495d9fc..0000000000 --- a/docs/admin/setup/web-server/caddy/Caddyfile +++ /dev/null @@ -1,15 +0,0 @@ -{ - on_demand_tls { - ask http://example.com - } -} - -coder.example.com, *.coder.example.com { - reverse_proxy localhost:3000 - tls { - on_demand - issuer acme { - email email@example.com - } - } -} diff --git a/docs/admin/setup/web-server/caddy/docker-compose.yaml b/docs/admin/setup/web-server/caddy/docker-compose.yaml deleted file mode 100644 index 962a40dc03..0000000000 --- a/docs/admin/setup/web-server/caddy/docker-compose.yaml +++ /dev/null @@ -1,57 +0,0 @@ -version: "3.9" -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:14.2" - 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: diff --git a/docs/manifest.json b/docs/manifest.json index 2a896617d9..a3ebdf9b98 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -699,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/docs/tutorials/faqs.md b/docs/tutorials/faqs.md index 4fda54804f..96dccf8047 100644 --- a/docs/tutorials/faqs.md +++ b/docs/tutorials/faqs.md @@ -62,9 +62,9 @@ troubleshooting. ### How do I configure NGINX as the reverse proxy in front of Coder? -[This doc](../admin/setup/web-server/nginx/index.md) in our repo explains in -detail how to configure NGINX with Coder so that our Tailscale Wireguard -networking functions properly. +[This tutorial](./reverse-proxy-nginx.md) in our docs explains in detail how to +configure NGINX with Coder so that our Tailscale Wireguard networking functions +properly. ### How do I hide some of the default icons in a workspace like VS Code Desktop, Terminal, SSH, Ports? diff --git a/docs/admin/setup/web-server/apache/index.md b/docs/tutorials/reverse-proxy-apache.md similarity index 98% rename from docs/admin/setup/web-server/apache/index.md rename to docs/tutorials/reverse-proxy-apache.md index 6ade417218..f11cc66ee4 100644 --- a/docs/admin/setup/web-server/apache/index.md +++ b/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/docs/admin/setup/web-server/caddy/index.md b/docs/tutorials/reverse-proxy-caddy.md similarity index 59% rename from docs/admin/setup/web-server/caddy/index.md rename to docs/tutorials/reverse-proxy-caddy.md index 12427bc506..7a7583491c 100644 --- a/docs/admin/setup/web-server/caddy/index.md +++ b/docs/tutorials/reverse-proxy-caddy.md @@ -11,31 +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 +2. Create a `docker-compose.yaml` file and add the following: - ```shell - # Create a project folder - cd $HOME - mkdir coder-with-caddy - cd coder-with-caddy + ```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 - # 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) + 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: ``` -1. Modify the [Caddyfile](./Caddyfile) and change the following values: +3. Create a `Caddyfile` and add the following: - - `localhost:3000`: Change to `coder:7080` (Coder container on Docker - network) + ```caddyfile + { + 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 + } + } + } + ``` + + Here; + + - `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 @@ -46,11 +116,23 @@ certificates, you'll need a domain name that resolves to your Caddy server. ### Standalone -1. If you haven't already, [install Coder](../../../../install/index.md) +1. If you haven't already, [install Coder](../install/index.md) 2. Install [Caddy Server](https://caddyserver.com/docs/install) -3. Copy our sample [Caddyfile](./Caddyfile) and change the following values: +3. Copy our sample `Caddyfile` and change the following values: + + ```caddyfile + { + on_demand_tls { + ask http://example.com + } + } + + coder.example.com, *.coder.example.com { + reverse_proxy coder:7080 + } + ``` > If you're installed Caddy as a system package, update the default Caddyfile > with `vim /etc/caddy/Caddyfile` @@ -59,14 +141,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`). @@ -116,7 +198,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/docs/admin/setup/web-server/nginx/index.md b/docs/tutorials/reverse-proxy-nginx.md similarity index 98% rename from docs/admin/setup/web-server/nginx/index.md rename to docs/tutorials/reverse-proxy-nginx.md index 7355498daa..36ac9f4a9a 100644 --- a/docs/admin/setup/web-server/nginx/index.md +++ b/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