extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2024-11-07 08:44:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #166 from openziti/qrkourier-patch-4

Browse Source 
add Nginx guide
This commit is contained in:
Ken Bingham 2023-01-19 13:10:53 -05:00 committed by GitHub
commit b92e7043c8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 88 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/v0.3_nginx_tls_guide.md Normal file
View File

@ -0,0 +1,88 @@
# Nginx Reverse Proxy for zrok
I'll assume you have a running zrok controller and public frontend and wish to front both with Nginx providing server TLS. Go back to [the hosting quickstart](v0.3_quickstart.md) if you still need to spin those up.
## Choose a Reverse Proxy Address
I'll use `https://api.zrok.quigley.com:443` in this example, and assume you already set up wildcard DNS like `*.zrok.quigley.com`. This lets us elect `api.zrok.quigley.com` as the controller DNS name, and forward any other incoming requests to the zrok public frontend.
## Obtain a Wildcard Server Certificate
You must complete a DNS challenge to obtain a wildcard certificate from Let's Encrypt. I'll assume you know how to create the necessary TXT record in the DNS zone you're using with zrok.
1. Install certbot: https://eff-certbot.readthedocs.io/en/stable/install.html
2. Run certbot with the manual plugin: https://certbot.eff.org/docs/using.html#manual
```bash
# install cert for *.zrok.quigley.com in /etc/letsencrypt
sudo certbot certonly --manual
````
## [Install Nginx](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)
## Configure Nginx
```
server {
listen 443 ssl;
server_name api.zrok.quigley.com;
ssl_certificate /etc/letsencrypt/live/zrok.quigley.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/zrok.quigley.com/privkey.pem;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
proxy_pass http://127.0.0.1:18080;
error_log /var/log/nginx/zrok-controller.log;
}
}
server {
listen 443 ssl;
server_name *.zrok.quigley.com;
ssl_certificate /etc/letsencrypt/live/zrok.quigley.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/zrok.quigley.com/privkey.pem;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
error_log /var/log/nginx/zrok-frontend.log;
proxy_busy_buffers_size 512k;
proxy_buffers 4 512k;
proxy_buffer_size 256k;
}
}
```
## Restart Nginx
Load the new configuration by restarting Nginx. Check the logs to make sure it's happy.
> Started A high performance web server and a reverse proxy server.
## Check the Firewall
If you followed the non-TLS quickstart then you may have opened 8080,108080/tcp in your firewall. You can go ahead and replace those exceptions with 443/tcp because only Nginx needs to be reachable for zrok to function.
## Update the zrok Frontend
List available frontends to obtain the token identifier of the frontend named "public". You may need to set `ZROK_ADMIN_TOKEN` or `ZROK_API_ENDPOINT` before running `zrok admin`.
```bash
$ zrok admin list frontends
TOKEN ZID PUBLIC NAME URL TEMPLATE CREATED AT UPDATED AT
2NiDTRYUww18 7DsLh9DXG public http://{token}.zrok.quigley.com:8080 2023-01-19 05:29:20.793 +0000 UTC 2023-01-19 06:17:25 +0000 UTC
```
Update the URL template to use Nginx.
```bash
$ zrok admin update frontend 2NiDTRYUww18 --url-template https://{token}.zrok.quigley.com:443
[ 0.028] INFO main.(*adminUpdateFrontendCommand).run: updated global frontend '2NiDTRYUww18'
```