Skip to content

docs: add nginx reverse-proxy example #6185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 33 commits into from
Feb 15, 2023
Merged
Changes from 1 commit
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
2c7f0cf
docs: Add nginx reverse-proxy example
matifali Feb 13, 2023
d29da64
change nginx example to to absolute path
matifali Feb 13, 2023
247a060
Merge branch 'coder:main' into rev-proxy-auto-tls
matifali Feb 13, 2023
3c247a5
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
8a96176
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
4f25817
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
099428a
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
d3913b3
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
7f8d795
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
3d306a4
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
69eb387
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
c1111b3
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
af32c58
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
b672a1f
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
f080259
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
838e008
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
23dd1e3
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
7a7e7e4
Update examples/web-server/nginx/README.md
matifali Feb 13, 2023
a5abc85
refactor: replaced bullets with numbered lists
matifali Feb 13, 2023
3f1353e
remove the ambiguous ip addr.
matifali Feb 13, 2023
8e5531d
fixed a typo
matifali Feb 13, 2023
8c343f0
correctly handle the wildcard subdomain
matifali Feb 13, 2023
86e7dae
simplified after testing
matifali Feb 13, 2023
7d28e51
fmt: prettier formatting
matifali Feb 13, 2023
a642933
Adapt to the coder style guide
matifali Feb 13, 2023
77149bc
fix: agent disconnection
matifali Feb 14, 2023
ff6fd37
Merge branch 'coder:main' into rev-proxy-auto-tls
matifali Feb 15, 2023
4b5362c
Update examples/web-server/nginx/README.md
matifali Feb 15, 2023
35247ed
Update docs/admin/configure.md
matifali Feb 15, 2023
30163f4
Update examples/web-server/nginx/README.md
matifali Feb 15, 2023
5b54368
updated with suggested changes
matifali Feb 15, 2023
4d0deb6
updated with requested changes
matifali Feb 15, 2023
065ed25
add reference to certbot docs for other dns providers
matifali Feb 15, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fmt: prettier formatting
  • Loading branch information
matifali committed Feb 13, 2023
commit 7d28e51b71a51407a3a8173c501bbd4817c7c8d8
143 changes: 73 additions & 70 deletions examples/web-server/nginx/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,37 +2,39 @@

## Requirements

1. Start a Coder deployment with a wildcard subdomain. See [this guide](https://coder.com/docs/coder/v1.20/setup/installation#step-1-create-a-subdomain) for more information.
1. You'll need a subdomain and the a wildcard subdomain configured that resolves to server's public ip.
1. Start a Coder deployment with a wildcard subdomain. See [this guide](https://coder.com/docs/v2/latest/admin/configure#wildcard-access-url) for more information.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed it was important to have HTTP_ADDRESS as 3000. Plus the access URL is also important to set.

Suggested change
1. Start a Coder deployment with a wildcard subdomain. See [this guide](https://coder.com/docs/v2/latest/admin/configure#wildcard-access-url) for more information.
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.

What do you think about replacing all cases with CODER_SUBDOMAIN with coder.example.com? We tend to do this in other places in our docs, such as in the Caddy docs.

Copy link
Member Author

@matifali matifali Feb 15, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that is a better option. I will replace all YOUR_SUBDOMAIN with CODER_SUBDOMAIN


2. You'll need a subdomain and the a wildcard subdomain configured that resolves to server's public ip.

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

2. Install NGINX (assuming you're on Debian/Ubuntu):
3. Install NGINX (assuming you're on Debian/Ubuntu):

```console
sudo apt install nginx
```
```console
sudo apt install nginx
```

3. Stop NGINX service:
4. Stop NGINX service:

```console
sudo systemctl stop nginx
```
```console
sudo systemctl stop nginx
```

## Adding Coder deployment subdomain

> This example assumes Coder is running locally on `127.0.0.1:3000` for the subdomain `YOUR_SUBDOMAIN` e.g. `coder.example.com`.

1. Create NGINX configuration for this app:

```console
sudo touch /etc/nginx/sites-available/YOUR_SUBDOMAIN
```
```console
sudo touch /etc/nginx/sites-available/YOUR_SUBDOMAIN
```

2. Activate this file:

```console
sudo ln -s /etc/nginx/sites-available/YOUR_SUBDOMAIN /etc/nginx/sites-enabled/YOUR_SUBDOMAIN
```
```console
sudo ln -s /etc/nginx/sites-available/YOUR_SUBDOMAIN /etc/nginx/sites-enabled/YOUR_SUBDOMAIN
```

## Install and configure LetsEncrypt Certbot

Expand All @@ -41,69 +43,70 @@
## Create DNS provider credentials

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

- Zone - DNS - Edit

2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:

```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
```
```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
```

3. Set the correct permissions:

```console
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
```
```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
```
```console
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
```

## Configure nginx
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Configure nginx
## Configure NGINX


1. Edit the file with:

```console
sudo nano /etc/nginx/sites-available/YOUR_SUBDOMAIN
```
```console
sudo nano /etc/nginx/sites-available/YOUR_SUBDOMAIN
```

2. Add the following content:

```nginx
server {
server_name YOUR_SUBDOMAIN *.YOUR_SUBDOMAIN;

# 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/YOUR_SUBDOMAIN/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/YOUR_SUBDOMAIN/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 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;
}
}
```
```nginx
server {
server_name YOUR_SUBDOMAIN *.YOUR_SUBDOMAIN;

# 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/YOUR_SUBDOMAIN/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/YOUR_SUBDOMAIN/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 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:
>
Expand All @@ -113,22 +116,22 @@

1. Create a new file in `/etc/cron.weekly`:

```console
sudo touch /etc/cron.weekly/certbot
```
```console
sudo touch /etc/cron.weekly/certbot
```

2. Make it executable:

```console
sudo chmod +x /etc/cron.weekly/certbot
```
```console
sudo chmod +x /etc/cron.weekly/certbot
```

3. And add this code:

```sh
#!/bin/sh
sudo certbot renew -q
```
```sh
#!/bin/sh
sudo certbot renew -q
```

## Restart NGINX

Expand Down