Skip to content

Commit 26876dc

Browse files
matifalibpmct
matifali
and
bpmct
authored
docs: add apache reverse-proxy example (#6213)
* docs: apache reverse proxy * fixed to correctly pass WebSocket headers * add a sample configuration file * updating with suggestions * Update coder.conf * fix http to https redirection * fix: upgrade http to https * Update examples/web-server/apache/README.md Co-authored-by: Ben Potter <me@bpmct.net> * add other dns providers documentation link --------- Co-authored-by: Ben Potter <me@bpmct.net> Co-authored-by: Ben Potter <ben@coder.com>
1 parent 9930664 commit 26876dc

File tree

3 files changed

+186
-1
lines changed

3 files changed

+186
-1
lines changed

‎docs/admin/configure.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,11 @@ subdomain that resolves to Coder (e.g. `*.coder.example.com`).
4242
> If you are providing TLS certificates directly to the Coder server, you must use a single certificate for the
4343
> root and wildcard domains. Multi-certificate support [is planned](https://github.com/coder/coder/pull/4150).
4444
45-
## TLS Certificates
45+
## TLS & Reverse Proxy
4646

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

49+
- Apache: [Run Coder with Apache and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/apache)
4950
- Caddy: [Run Coder with Caddy and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/caddy)
5051
- NGINX: [Run Coder with Nginx and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/nginx)
5152

‎examples/web-server/apache/README.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# How to use Apache as a reverse-proxy with LetsEncrypt
2+
3+
## Requirements
4+
5+
1. Start a Coder deployment and be sure to set the following [configuration values](https://coder.com/docs/v2/latest/admin/configure):
6+
7+
```console
8+
CODER_HTTP_ADDRESS=127.0.0.1:3000
9+
CODER_ACCESS_URL=https://coder.example.com
10+
CODER_WILDCARD_ACCESS_URL=*coder.example.com
11+
```
12+
13+
Throughout the guide, be sure to replace `coder.example.com` with the domain you intend to use with Coder.
14+
15+
2. Configure your DNS provider to point your coder.example.com and \*.coder.example.com to your server's public IP address.
16+
17+
> 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.
18+
19+
3. Install Apache (assuming you're on Debian/Ubuntu):
20+
21+
```console
22+
sudo apt install apache2
23+
```
24+
25+
4. Enable the following Apache modules:
26+
27+
```console
28+
sudo a2enmod proxy
29+
sudo a2enmod proxy_http
30+
sudo a2enmod ssl
31+
sudo a2enmod rewrite
32+
```
33+
34+
5. Stop Apache service and disable default site:
35+
36+
```console
37+
sudo a2dissite 000-default.conf
38+
sudo systemctl stop apache2
39+
```
40+
41+
## Install and configure LetsEncrypt Certbot
42+
43+
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.
44+
45+
## Create DNS provider credentials
46+
47+
> 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).
48+
49+
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:
50+
51+
- Zone - DNS - Edit
52+
53+
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:
54+
55+
```ini
56+
dns_cloudflare_api_token = YOUR_API_TOKEN
57+
```
58+
59+
```console
60+
mkdir -p ~/.secrets/certbot
61+
touch ~/.secrets/certbot/cloudflare.ini
62+
nano ~/.secrets/certbot/cloudflare.ini
63+
```
64+
65+
3. Set the correct permissions:
66+
67+
```console
68+
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
69+
```
70+
71+
## Create the certificate
72+
73+
1. Create the wildcard certificate:
74+
75+
```console
76+
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
77+
```
78+
79+
## Configure Apache
80+
81+
> This example assumes Coder is running locally on `127.0.0.1:3000` and that you're using `coder.example.com` as your subdomain.
82+
83+
1. Create Apache configuration for Coder:
84+
85+
```console
86+
sudo nano /etc/apache2/sites-available/coder.conf
87+
```
88+
89+
2. Add the following content:
90+
91+
```apache
92+
# Redirect HTTP to HTTPS
93+
<VirtualHost *:80>
94+
ServerName coder.example.com
95+
ServerAlias *.coder.example.com
96+
Redirect permanent / https://coder.example.com/
97+
</VirtualHost>
98+
99+
<VirtualHost *:443>
100+
ServerName coder.example.com
101+
ServerAlias *.coder.example.com
102+
ErrorLog ${APACHE_LOG_DIR}/error.log
103+
CustomLog ${APACHE_LOG_DIR}/access.log combined
104+
105+
ProxyPass / http://127.0.0.1:3000/
106+
ProxyPassReverse / http://127.0.0.1:3000/
107+
ProxyRequests Off
108+
ProxyPreserveHost On
109+
110+
RewriteEngine On
111+
# Websockets are required for workspace connectivity
112+
RewriteCond %{HTTP:Connection} Upgrade [NC]
113+
RewriteCond %{HTTP:Upgrade} websocket [NC]
114+
RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]
115+
116+
SSLCertificateFile /etc/letsencrypt/live/coder.example.com/fullchain.pem
117+
SSLCertificateKeyFile /etc/letsencrypt/live/coder.example.com/privkey.pem
118+
</VirtualHost>
119+
```
120+
121+
> Don't forget to change: `coder.example.com` by your (sub)domain
122+
123+
3. Enable the site:
124+
125+
```console
126+
sudo a2ensite coder.conf
127+
```
128+
129+
4. Restart Apache:
130+
131+
```console
132+
sudo systemctl restart apache2
133+
```
134+
135+
## Refresh certificates automatically
136+
137+
1. Create a new file in `/etc/cron.weekly`:
138+
139+
```console
140+
sudo touch /etc/cron.weekly/certbot
141+
```
142+
143+
2. Make it executable:
144+
145+
```console
146+
sudo chmod +x /etc/cron.weekly/certbot
147+
```
148+
149+
3. And add this code:
150+
151+
```sh
152+
#!/bin/sh
153+
sudo certbot renew -q
154+
```
155+
156+
And that's it, you should now be able to access Coder at your sub(domain) e.g. `https://coder.example.com`.

‎examples/web-server/apache/coder.conf

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<VirtualHost *:80>
2+
ServerName coder.example.com
3+
ServerAlias *.coder.example.com
4+
<Location "/">
5+
Redirect permanent "https://%{HTTP_HOST}%{REQUEST_URI}"
6+
</Location>
7+
</VirtualHost>
8+
9+
<VirtualHost *:443>
10+
ServerName coder.example.com
11+
ServerAlias *.coder.example.com
12+
ErrorLog ${APACHE_LOG_DIR}/error.log
13+
CustomLog ${APACHE_LOG_DIR}/access.log combined
14+
15+
ProxyPass / http://127.0.0.1:3000/
16+
ProxyPassReverse / http://127.0.0.1:3000/
17+
ProxyRequests Off
18+
ProxyPreserveHost On
19+
20+
RewriteEngine On
21+
RewriteCond %{HTTP:Connection} Upgrade [NC]
22+
RewriteCond %{HTTP:Upgrade} websocket [NC]
23+
RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]
24+
25+
SSLCertificateFile /etc/letsencrypt/live/coder.example.com/fullchain.pem
26+
SSLCertificateKeyFile /etc/letsencrypt/live/coder.example.com/privkey.pem
27+
</VirtualHost>
28+

0 commit comments

Comments
 (0)