We engineered a fully automated domain provisioning system that handles the entire lifecycle of custom domains — from DNS validation through Nginx virtual host configuration to Let's Encrypt SSL certificate issuance — all orchestrated through a single REST API call with zero downtime.
The challenge
SuperOkay's white-label SaaS platform needed to support hundreds of clients bringing their own custom domains — each requiring DNS validation, Nginx reverse proxy configuration, and HTTPS with valid SSL certificates. Doing this manually was unsustainable: every new domain meant SSH-ing into production servers, hand-editing Nginx configs, running Certbot commands, and praying nothing broke. One misconfigured vhost could take down the entire proxy layer. The system needed to be fully automated, idempotent, and bulletproof — capable of provisioning a new custom domain with HTTPS in seconds, not hours, while preventing race conditions from concurrent requests hitting the same domain.
Our solution
We built vhost-manager as a dedicated Node.js microservice running on Koa.js with a clean REST API. The service orchestrates a multi-step provisioning pipeline: first, it validates DNS CNAME records to confirm the domain points to our infrastructure. Then it generates Nginx virtual host configurations from Handlebars templates — producing both HTTP and HTTPS variants — and activates them via symlinks in Nginx's sites-enabled directory. SSL certificates are provisioned automatically through Certbot with Let's Encrypt integration, and on successful issuance the service swaps the HTTP-only config for the full HTTPS version and triggers an Nginx reload. A domain-level locking mechanism prevents concurrent provisioning requests from colliding, and the entire pipeline includes automatic rollback on any failure — removing configs, disabling vhosts, and restoring Nginx to its previous state. The service handles creation, deletion, and status queries, all behind HTTP basic authentication.
Results
- Reduced custom domain provisioning from hours of manual work to a single API call completing in seconds
- Automated the full SSL lifecycle with Let's Encrypt certificate issuance and Nginx HTTPS configuration
- Engineered domain-level locking preventing race conditions from concurrent provisioning requests
- Built automatic rollback pipeline that restores Nginx to stable state on any provisioning failure
- Eliminated human error in Nginx configuration through Handlebars template-driven vhost generation
- Enabled SuperOkay to scale to hundreds of white-label custom domains with zero operational overhead