diff --git a/docs/v0.3_getting_started/getting_started.md b/docs/v0.3_getting_started/getting_started.md index 7e08b17a..f5fc3786 100644 --- a/docs/v0.3_getting_started/getting_started.md +++ b/docs/v0.3_getting_started/getting_started.md @@ -323,7 +323,7 @@ And now if we refresh the frontend endpoint URL in the web browser, we'll see an ![zrok docs share](images/zrok_docs_share.png) -With the reserved share, we're free stop and restart the `zrok share reserved` command as many times as we want, without losing the token for our share. +With the reserved share, we're free to stop and restart the `zrok share reserved` command as many times as we want, without losing the token for our share. When we're done with the reserved share, we can _release_ it using this command: @@ -369,4 +369,4 @@ You use the `zrok reserve` command to create _reserved shares_. Reserved shares Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](../v0.3_self_hosting_guide.md) for details. [openziti]: https://docs.openziti.io/ "OpenZiti" -[ zrok-download]: https://zrok.io "Zrok Download" \ No newline at end of file +[ zrok-download]: https://zrok.io "Zrok Download" 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' +``` diff --git a/docs/v0.3_self_hosting_guide.md b/docs/v0.3_self_hosting_guide.md index a4da912d..2fab9be1 100644 --- a/docs/v0.3_self_hosting_guide.md +++ b/docs/v0.3_self_hosting_guide.md @@ -21,7 +21,7 @@ You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when bu ## Configure the Controller -Create a controller configuration file in `etc/ctrl.yml`. +Create a controller configuration file in `etc/ctrl.yml`. The controller does not provide server TLS, but you may front the server with a reverse proxy. This example will expose the non-TLS listener for the controller. ```yaml # _____ __ ___ | | __ @@ -144,7 +144,7 @@ Now our `zrok` controller is fully configured. ## Configure the Public Frontend -Create `etc/http-frontend.yml`. You must reiterate the pattern you expressed in the public frontend URL template as a `host_match` pattern, and you may change the default address where the frontend will listen for public access requests. +Create `etc/http-frontend.yml`. You must reiterate the pattern you expressed in the public frontend URL template as a `host_match` pattern, and you may change the default address where the frontend will listen for public access requests. The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the `Host` header supplied by the viewer. This example will expose the non-TLS listener for the frontend. ```yaml host_match: zrok.quigley.com