synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-21 01:28:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add nginx reverse-proxy example (#6185)

Browse Source 
* docs: Add nginx reverse-proxy example

This PR adds nginx reverse-proxy example to provision coder with tls certificate using letsencrypt certbot.

This will partially resolve #6086.

* change nginx example to to absolute path

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* refactor: replaced bullets with numbered lists

* remove the ambiguous ip addr.

* fixed a typo

* correctly handle the wildcard subdomain

* simplified after testing

* fmt: prettier formatting

* Adapt to the coder style guide

* fix: agent disconnection

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update docs/admin/configure.md

Co-authored-by: Ben Potter <me@bpmct.net>

* Update examples/web-server/nginx/README.md

Co-authored-by: Ben Potter <me@bpmct.net>

* updated with suggested changes

* updated with requested changes

* add reference to certbot docs for other dns providers

---------

Co-authored-by: Ben Potter <me@bpmct.net>
This commit is contained in:
Muhammad Atif Ali
2023-02-15 22:18:54 +03:00
committed by GitHub
parent 3b7b96ac28
commit 786ad8d8b1
2 changed files with 169 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/admin/configure.md
View File

@ -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. <https://coder.example.com>). 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 (<https://repo1.maven.org/maven2>) 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

163
examples/web-server/nginx/README.md Normal file
View File

@ -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`.