From c7ed9e1eddc8216d11d19ff98c086a84b1af2b55 Mon Sep 17 00:00:00 2001 From: Ken Bingham Date: Thu, 19 Jan 2023 10:26:28 -0500 Subject: [PATCH] add Nginx guide --- docs/v0.3_nginx_tls_guide.md | 88 ++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/v0.3_nginx_tls_guide.md diff --git a/docs/v0.3_nginx_tls_guide.md b/docs/v0.3_nginx_tls_guide.md new file mode 100644 index 00000000..b5878273 --- /dev/null +++ b/docs/v0.3_nginx_tls_guide.md @@ -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' +```