diff --git a/docs/admin/configure.md b/docs/admin/configure.md index ea28afaa403ef..7132f0308d5d2 100644 --- a/docs/admin/configure.md +++ b/docs/admin/configure.md @@ -4,7 +4,7 @@ of the options, run `coder server --help` on the host. ## Access URL `CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the external URL -that users and workspaces use to connect to Coder (e.g. https://coder.example.com). This +that users and workspaces use to connect to Coder (e.g. ). This should not be localhost. > Access URL should be a external IP address or domain with DNS records pointing to Coder. @@ -46,13 +46,14 @@ subdomain that resolves to Coder (e.g. `*.coder.example.com`). 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, for example. -- Example: [Run Coder with Caddy and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/caddy) +- Caddy: [Run Coder with Caddy and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/caddy) +- NGINX: [Run Coder with Nginx and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/nginx) ## PostgreSQL Database Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information. Use `CODER_PG_CONNECTION_URL` to set the database that Coder connects to. If unset, PostgreSQL binaries will be -downloaded from Maven (https://repo1.maven.org/maven2) and store all data in the config root. +downloaded from Maven () and store all data in the config root. > Postgres 13 is the minimum supported version. @@ -60,8 +61,8 @@ If you are using the built-in PostgreSQL deployment and need to use `psql` (aka the PostgreSQL interactive terminal), output the connection URL with the following command: ```console -$ coder server postgres-builtin-url -$ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1" +coder server postgres-builtin-url +psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1" ``` ## System packages diff --git a/examples/web-server/nginx/README.md b/examples/web-server/nginx/README.md new file mode 100644 index 0000000000000..c09edb5099db0 --- /dev/null +++ b/examples/web-server/nginx/README.md @@ -0,0 +1,163 @@ +# 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](https://coder.com/docs/v2/latest/admin/configure): + + ```console + 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): + + ```console + sudo apt install nginx + ``` + +4. Stop NGINX service: + + ```console + 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: + + ```console + sudo touch /etc/nginx/sites-available/coder.example.com + ``` + +2. Activate this file: + + ```console + 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://dash.cloudflare.com/profile/api-tokens) 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 + ``` + + ```console + mkdir -p ~/.secrets/certbot + touch ~/.secrets/certbot/cloudflare.ini + nano ~/.secrets/certbot/cloudflare.ini + ``` + +3. Set the correct permissions: + + ```console + sudo chmod 600 ~/.secrets/certbot/cloudflare.ini + ``` + +## Create the certificate + +1. Create the wildcard certificate: + + ```console + 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: + + ```console + 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: + + ```console + sudo nginx -t + ``` + +## Refresh certificates automatically + +1. Create a new file in `/etc/cron.weekly`: + + ```console + sudo touch /etc/cron.weekly/certbot + ``` + +2. Make it executable: + + ```console + sudo chmod +x /etc/cron.weekly/certbot + ``` + +3. And add this code: + + ```sh + #!/bin/sh + sudo certbot renew -q + ``` + +## Restart NGINX + +```console +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`.