Aqua Direct — Reverse Proxy server handling custom domains

Aqua Direct is reverse proxy servers that handles custom domain in Recrutability, there SSL certification to keep them secure, it resides on recrutability.me.

Custom Domains?

Aqua Direct is built for one specific feature "Custom Domains", Recrutability provides portfolio hosting and a subdomain for free but professionals users want portfolio to be accessible on their own domain, so hosting should remain same but it should be accessible by different domain. Which means the contents server by username.recrutability.com and somedomain.com should be same if they're linked, an easy way is to point custom domain to recrutability.me IP and then Aqua Direct can serve the profile. But there two major problems.

1. Domain to IP is a breaking point, because Recrutability IP can change any time in future and all they linked domains would have to change the IP.

2. Because content is served by Aqua Direct, it's also responsible for custom domain SSL certificate.

3. Aqua Direct should be able to generate SSL certificates without any manual work.

Solution to #1 — CNAME to the rescue

DNS provides a feature to map one domain to another domain known as CNAME ( Canonical name) record. With CNAME we can map our custom domain to recrutability.me domain and forget about IP thing, the domain would eventually resolve to recrutability.me IP even if it changes. This resolves our first problem.

Solution to #2 — Let's Encrypt!

No one likes "Not secure" warning on their domains, but one can not generate SSL certificates by their own as it's not acceptable by web browsers, certificates generated by recognizable authorities like DigiCert is only acceptable but most of them charge fees yearly, and for Recrutability it isn't best solution.

Fortunately Let's encrypt exists in this time, it's a non-profit recognizable certificate authority, which provides free SSL certificate valid for 90 days and can be regenerated, all free of cost! Which means Aqua Direct can generate custom domains certificates from Let's Encrypt free of cost.

Solution to #3 — Let's Encrypt API and greenlock

Because users of Recrutability can link their domain at any time, they don't want to wait for a day or two for their site to be certified, they want their site to be secure in 5 minutes and renewed in 90 days before the certificate expires. So the problem is getting the certificate in 5 minutes, renew certificates before their expiry and there can also be multiple certification requests, for a human this a cumbersome and repetitive process and that's where computers at good at.

Let's encrypt provides API to automatically generate SSL certificates without any need of humans, API partially solves our problem but what about renewing? We've to keep track of every certificate and generate a new certificate before it expires. We could implement certificate generation via API, implement Let's encrypt challenges and auto renewing but why reinvent the wheel, alot of face this problem so many solutions already exists and greenlock is one of them. It can handle new SSL certificates generation, and auto renews them so we won't have to worry about them.

Seamless Proxying

Recrutability itself doesn't contain any implementation to resolve custom domain to any portfolios, it only serves portfolios on subdomain like humayun.recrutability.com to keep the logic simple. To serve the content of humayun.recrutability.com whenever it's requested from www.humayun.io custom domain Aqua Direct stores a pairs mapping in it's in-memory database. So one of the pair in its database is www.humayun.io → humayun.recrutability.com.

Which means whenever the www.humayun.io domain is requested content of humayun.recrutability.com should be served but the question is how? because only Recrutability.com can serve content.

HTTP host Header!

Every HTTP request contains a "host" header which defines the hostname as in the following figure from chrome.

Recrutability reads this header and serves the portfolio of the user representing by the subdomain ( just before ".recrutability.com"), but it doesn't handle domains other than recrutability.com. So we need to provide a correct host value whenever a custom domain is requested, in short we need to rewrite the request header and then forward ( proxy ) the request to actual Recrutability server.

Host header rewriting

A request represented by the browser for www.humayun.io looks like this.

This request comes to Aqua Direct which then modify this request ( the browser is unware of this ) by rewriting host according to the pair value (humayun.recrutability.com for this request) and then forward ( proxy ) this request to recrutability.com server ( locally because they're both on same network ), Recrutability server simply check the username in subdomain and respond with corresponding portfolio which then Aqua Direct sends back to browser. The whole process is seamless, neither browser nor user is unaware of this proxying.

Conclusion

To match expectations of customers and to provide premium features alot of technical challenges have to be resolved. Aqua Direct was born to power the Recrutability custom domain feature but it's all worth it, my own portfolio domain ( www.humayun.io ) is linked to Recrutability, so I won't have to face SSL or hosting issues.