opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix links for revere-proxy docs (#15026)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2024-10-10 05:31:19 +00:00
committed by GitHub
parent 9d02269191
commit ab6cb1a787
9 changed files with 128 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/faqs.md
+3 -3
View File
@@ -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?
docs/tutorials/reverse-proxy-apache.md
+172
View File
@@ -0,0 +1,172 @@
# How to use Apache as a reverse-proxy with LetsEncrypt
## Requirements
1. Start a Coder deployment and be sure to set the following
[configuration values](../admin/setup/index.md):
```env
CODER_HTTP_ADDRESS=127.0.0.1:3000
CODER_ACCESS_URL=https://coder.example.com
CODER_WILDCARD_ACCESS_URL=*coder.example.com
```
Throughout the guide, be sure to replace `coder.example.com` with the domain
you intend to use with Coder.
2. Configure your DNS provider to point your coder.example.com and
\*.coder.example.com to your server's public IP address.
> For example, to use `coder.example.com` as your subdomain, configure
> `coder.example.com` and `*.coder.example.com` to point to your server's
> public ip. This can be done by adding A records in your DNS provider's
> dashboard.
3. Install Apache (assuming you're on Debian/Ubuntu):
```shell
sudo apt install apache2
```
4. Enable the following Apache modules:
```shell
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod ssl
sudo a2enmod rewrite
```
5. Stop Apache service and disable default site:
```shell
sudo a2dissite 000-default.conf
sudo systemctl stop apache2
```
## Install and configure LetsEncrypt Certbot
1. Install LetsEncrypt Certbot: Refer to the
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
Be sure to pick the wildcard tab and select your DNS provider for
instructions to install the necessary DNS plugin.
## Create DNS provider credentials
> This example assumes you're using CloudFlare as your DNS provider. For other
> providers, refer to the
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
1. Create an API token for the DNS provider you're using: e.g.
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
with the following permissions:
- Zone - DNS - Edit
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
content:
```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
```
```shell
mkdir -p ~/.secrets/certbot
touch ~/.secrets/certbot/cloudflare.ini
nano ~/.secrets/certbot/cloudflare.ini
```
3. Set the correct permissions:
```shell
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
```
## Create the certificate
1. Create the wildcard certificate:
```shell
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
```
## Configure Apache
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
> you're using `coder.example.com` as your subdomain.
1. Create Apache configuration for Coder:
```shell
sudo nano /etc/apache2/sites-available/coder.conf
```
2. Add the following content:
```apache
# Redirect HTTP to HTTPS
<VirtualHost *:80>
ServerName coder.example.com
ServerAlias *.coder.example.com
Redirect permanent / https://coder.example.com/
</VirtualHost>
<VirtualHost *:443>
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
</VirtualHost>
```
> Don't forget to change: `coder.example.com` by your (sub)domain
3. Enable the site:
```shell
sudo a2ensite coder.conf
```
4. Restart Apache:
```shell
sudo systemctl restart apache2
```
## Refresh certificates automatically
1. Create a new file in `/etc/cron.weekly`:
```shell
sudo touch /etc/cron.weekly/certbot
```
2. Make it executable:
```shell
sudo chmod +x /etc/cron.weekly/certbot
```
3. And add this code:
```shell
#!/bin/sh
sudo certbot renew -q
```
And that's it, you should now be able to access Coder at your sub(domain) e.g.
`https://coder.example.com`.
docs/tutorials/reverse-proxy-caddy.md
+269
View File
@@ -0,0 +1,269 @@
# Caddy
This is an example configuration of how to use Coder with
[caddy](https://caddyserver.com/docs). To use Caddy to generate TLS
certificates, you'll need a domain name that resolves to your Caddy server.
## Getting started
### With docker-compose
1. [Install Docker](https://docs.docker.com/engine/install/) and
[Docker Compose](https://docs.docker.com/compose/install/)
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:
```
3. Create a `Caddyfile` and add the following:
```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)
4. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the
domain you're using in your Caddyfile.
```shell
export CODER_ACCESS_URL=https://coder.example.com
export CODER_WILDCARD_ACCESS_URL=*.coder.example.com
docker compose up -d # Run on startup
```
### Standalone
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` 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`
- `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](../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](../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`).
5. Start the Caddy server:
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a
system service:
```shell
sudo systemctl restart caddy
```
Or run a standalone server:
```shell
caddy run
```
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or
another firewall to disable external traffic outside of Caddy.
```shell
# Check status of UncomplicatedFirewall
sudo ufw status
# Allow SSH
sudo ufw allow 22
# Allow HTTP, HTTPS (Caddy)
sudo ufw allow 80
sudo ufw allow 443
# Deny direct access to Coder server
sudo ufw deny 3000
# Enable UncomplicatedFirewall
sudo ufw enable
```
7. Navigate to your Coder URL! A TLS certificate should be auto-generated on
your first visit.
## Generating wildcard certificates
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](../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
wildcard certificate, which requires an explicit DNS challenge and additional
Caddy modules.
1. Install a custom Caddy build that includes the
[caddy-dns](https://github.com/caddy-dns) module for your DNS provider (e.g.
CloudFlare, Route53).
- Docker:
[Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules)
with the module for your DNS provider. Be sure to reference the new image
in the `docker-compose.yaml`.
- Standalone:
[Download a custom Caddy build](https://caddyserver.com/download) with the
module for your DNS provider. If you're using Debian/Ubuntu, you
[can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian)
to use the new build.
2. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve
the DNS challenge for wildcard certificates.
For example, for AWS Route53:
```diff
tls {
- on_demand
- issuer acme {
- email email@example.com
- }
+ dns route53 {
+ max_retries 10
+ aws_profile "real-profile"
+ access_key_id "AKI..."
+ secret_access_key "wJa..."
+ token "TOKEN..."
+ region "us-east-1"
+ }
}
```
> Configuration reference from
> [caddy-dns/route53](https://github.com/caddy-dns/route53).
And for CloudFlare:
Generate a
[token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
with the following permissions:
- Zone:Zone:Edit
```diff
tls {
- on_demand
- issuer acme {
- email email@example.com
- }
+ dns cloudflare CLOUDFLARE_API_TOKEN
}
```
> Configuration reference from
> [caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare).
docs/tutorials/reverse-proxy-nginx.md
+179
View File
@@ -0,0 +1,179 @@
# How to use NGINX as a reverse-proxy with LetsEncrypt
## Requirements
1. Start a Coder deployment and be sure to set the following
[configuration values](../admin/setup/index.md):
```env
CODER_HTTP_ADDRESS=127.0.0.1:3000
CODER_ACCESS_URL=https://coder.example.com
CODER_WILDCARD_ACCESS_URL=*.coder.example.com
```
Throughout the guide, be sure to replace `coder.example.com` with the domain
you intend to use with Coder.
2. Configure your DNS provider to point your coder.example.com and
\*.coder.example.com to your server's public IP address.
> For example, to use `coder.example.com` as your subdomain, configure
> `coder.example.com` and `*.coder.example.com` to point to your server's
> public ip. This can be done by adding A records in your DNS provider's
> dashboard.
3. Install NGINX (assuming you're on Debian/Ubuntu):
```shell
sudo apt install nginx
```
4. Stop NGINX service:
```shell
sudo systemctl stop nginx
```
## Adding Coder deployment subdomain
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
> you're using `coder.example.com` as your subdomain.
1. Create NGINX configuration for this app:
```shell
sudo touch /etc/nginx/sites-available/coder.example.com
```
2. Activate this file:
```shell
sudo ln -s /etc/nginx/sites-available/coder.example.com /etc/nginx/sites-enabled/coder.example.com
```
## Install and configure LetsEncrypt Certbot
1. Install LetsEncrypt Certbot: Refer to the
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
Be sure to pick the wildcard tab and select your DNS provider for
instructions to install the necessary DNS plugin.
## Create DNS provider credentials
> This example assumes you're using CloudFlare as your DNS provider. For other
> providers, refer to the
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
1. Create an API token for the DNS provider you're using: e.g.
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
with the following permissions:
- Zone - DNS - Edit
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
content:
```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
```
```shell
mkdir -p ~/.secrets/certbot
touch ~/.secrets/certbot/cloudflare.ini
nano ~/.secrets/certbot/cloudflare.ini
```
3. Set the correct permissions:
```shell
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
```
## Create the certificate
1. Create the wildcard certificate:
```shell
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
```
## Configure nginx
1. Edit the file with:
```shell
sudo nano /etc/nginx/sites-available/coder.example.com
```
2. Add the following content:
```nginx
server {
server_name coder.example.com *.coder.example.com;
# HTTP configuration
listen 80;
listen [::]:80;
# HTTP to HTTPS
if ($scheme != "https") {
return 301 https://$host$request_uri;
}
# HTTPS configuration
listen [::]:443 ssl ipv6only=on;
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/coder.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/coder.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3000; # Change this to your coder deployment port default is 3000
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
}
}
```
> Don't forget to change: `coder.example.com` by your (sub)domain
3. Test the configuration:
```shell
sudo nginx -t
```
## Refresh certificates automatically
1. Create a new file in `/etc/cron.weekly`:
```shell
sudo touch /etc/cron.weekly/certbot
```
2. Make it executable:
```shell
sudo chmod +x /etc/cron.weekly/certbot
```
3. And add this code:
```shell
#!/bin/sh
sudo certbot renew -q
```
## Restart NGINX
```shell
sudo systemctl restart nginx
```
And that's it, you should now be able to access Coder at your sub(domain) e.g.
`https://coder.example.com`.