wildcard subdomain

Hosting Custom Sub-domains with Express ,Cpanel & Nginx.

Collins Hillary
5 min readNov 10, 2022

--

Hi there, in this article I will be showing you how to create and accept custom subdomains in your application via Nginx and Cpanel setups.

Prerequisite:

The following are the prerequisite of this article.

  1. Knowledge of setting up and hosting an Express app.
  2. Knowledge of setting up a server with Nginx.
  3. Have a Cpanel account with a domain.

Just to get started and to basically give you an idea of what this article will help you achieve, you will be able to create the same setup as some of the applications below in terms of customization of the domains for your application and clients. Example of some Applications using custom subdomains are:

  1. Heroku — a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud.
  2. Entraway — a gateway as a service (GAAS) that allows developers to create multiple gateways for their different services without exposing their back-end infrastructure.

Let’s get started.

A) SETTING UP THE EXPRESS APP

Let’s setup our simple express application that we will use to test if our custom domain setup is working.Create a project folder called node_subdomain then Initiate an express project using the following command.

npx express-generator — view ejs

Our current structure is as below.

Now there are some node/express packages that would allow you to capture subdomains easily , e.g express-subdomain. But we won’t be using that, we will utilise the normal request headers to capture the subdomain.

So in our routes/index.js file add the following code.

var express = require('express');var router = express.Router();router.get('/', function(req, res, next) {let custom_domain = req.headers['x-subdomain'] //This will get the x-subdomain header set and put it into our variableres.status(200).send(custom_domain)});module.exports = router;

Basically what the code above does is get the subdomain from a header called x-subdomain. This means on each request we receive into this route we should expect a request header called x-subdomain so as to achieve our custom subdomain objective.

B) SETTING UP THE WILDCARD DOMAIN

Now, let’s setup a wildcard domain on our Cpanel. This is quite simple, what we do is login to our Cpanel and follow the following steps:

  1. Click on domains under the domains section

Setup a wildcard domain like below by just inserting an asterisk*” before your domain name.

2. With our domain set, now click on Zone Editor.

then we will setup the server ip address (this is where you app and nginx is running on) on our wildcard domain A record as below.

This will take around an hour or less to propagate.

Great you are almost done. Now that we have our express app running on our server, and the A record setup in our Cpanel. We will now setup our Nginx config file.

C) SETTING UP THE NGINX CONFIG FILE

1. Open up your server and navigate to your Nginx config file and open it for editing.It’s normally found on this path /etc/nginx/sites-available.

Depending with how you have setup you Nginx server, I want you to notice a few things that you can add to your server.

Note: This setup works with both redirecting your custom domains to different root locations or as a proxy.

I’m using Nginx as a proxy. So look at the image below and notice the two sections that you will add to your server blocks.

Now the two section are the most important, add them to your nginx config, save and restart nginx. What this will do to all your request will be as follows.

A request to “collins.mydomain.com” will be captured and the “collins” subdomain will be added to the x-subdomain header as the request proceeds to our express application which we capture the subdomain “collins” by extracting the x-subdomain header from the request.

And that’s it.

Recap:

  1. We created an express application that will extract our dynamic ,custom subdomain from each request from the x-subdomain header.
  2. We then created a wildcard subdomain on the Cpanel and added our server ip address via the Zone Editor still on the Cpanel so that all our wildcard domain request can be redirected to our nginx server.
  3. We finally modified the nginx config file to allow wildcard domains as our server_name and set the subdomain value to our custom x-subdomain header. Where our express app can now extract the header and access the custom, dynamic subdomain.

That was simple right?

Great, that’s it from my side. Incase of any queries and help setting up feel free to reach out.

Happy Coding!

Author: Collins .H. Munene

Socials: LinkedIn

Profession: Software Engineer | Security Analyst | Immersive Tech Developer | Mentor

Sponsored by: Devligence Limited

--

--

Collins Hillary

Software and Immersive Tech Developer and Security Analyst