NGINX Reverse Proxy for zrok

Walkthrough Video

Before You Begin

I'll assume you have a running zrok controller and frontend and wish to front both with NGINX providing server TLS. Go back to Self-Hosting Guide 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

   # install cert for *.zrok.quigley.com in /etc/letsencrypt
   sudo certbot certonly --manual

Install NGINX

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;
    }

}

map $http_upgrade $connection_upgrade {
    default      keep-alive;
    'websocket'  upgrade;
    ''           close;
}

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;

      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
    }
}

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,18080/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.

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

$ zrok admin update frontend 2NiDTRYUww18 --url-template https://{token}.zrok.quigley.com:443
[   0.028]    INFO main.(*adminUpdateFrontendCommand).run: updated global frontend '2NiDTRYUww18'