Important

The author of this guide is not as familiar with nginx as he is with Caddy. As such, this guide is sadly lacking compared to the Caddy guide. Information, pointers to relevant documentation, and patches are more than welcome.

Getting started

In here, I assume that iocaine has already been configured and deployed, using a custom request handler. Lets assume that we have a site running at [::1]:8080, and we want to serve that with nginx. Normally, that would look something like this:

server {
  server_name blog.example.com;

  location / {
    proxy_set_header Host $host;
    proxy_pass http://[::1]:8080;
  }
}

Delegating decisions to iocaine

The modern way of running iocaine is to let it do the decision: pipe everything through to it, and let it decide what to do with the request. It will either serve it garbage or a challenge (and respond to the reverse proxy with a HTTP 200), or it will signal the reverse proxy to serve the real deal (by sending it a HTTP 421 response).

As such, we’ll have to wrap the above to match this expectation:

upstream iocaine {
  server 127.0.0.1:42069;
}
server {
  server_name blog.example.com;
  
  location / {
    proxy_pass http://iocaine;
    proxy_cache off;
    proxy_intercept_errors on;
    error_page 421 = @fallback;
  }
  
  location @fallback {
    proxy_pass http://[::1]:8080;
  }
}

As the author of this guide is not all that familiar with nginx, further optimizations, such as only sending GET and HEAD requests to iocaine, and automatically serving the real deal for other methods, is yet to be documented.