Setting up a custom domain for your local apps (Mac OS & Linux)

Hey there 👋

In this article, we would be covering how to set up a custom domain on a local machine. There is no prerequisite to go through the process. You should have a computer though.

So, what’s a custom domain?

A custom domain is a unique branded label that’s connected to the IP (Internet Provider) address from which a website is served. To visit a particular site, you can type its domain name into the address bar of your browser.

Your local computer is referred to as “localhost” by default. However, you can also create a custom domain name for your local server instead of using localhost.

When you build web applications on your local machine using server environments like NodeJS or XAMPP, the URL is usually assigned to 127.0.0.1 or localhost. However, you may want to change that local domain name to something else like hello-world.local, mysite.com, website.dev, etc.

Things to look out for:

• You shouldn’t use an existing website in the HOSTS file.

A hosts file is a component of operating systems that can also translate a domain name into an IP address. Records published in your local HOSTS file supersede what it would find from querying DNS (Domain Name Server) — so putting an entry into HOSTS might prevent you from accessing that website. For example, adding an entry that resolves google.com to localhost will prevent you from accessing google.com. In that example, any change or disruption to the IP address placed into your HOSTS file will result in you no longer being able to access the site.

• Modifying your HOSTS file can be a security vulnerability.

Just like the access challenge mentioned above, modifying your HOSTS file can become a vulnerability to your computer. If one were to go along with modifying the file, one of the steps taken would be to change the security settings of the file itself because it is protected by default in most operating systems to prevent alteration.

This is intentional! One of the reasons is that it becomes the major target of malware to spread viruses in your computer when accessible. The HOSTS file can be edited when your computer gets infected — it can likely write entries that may make your typical web-browser redirect to things that are much more nefarious.

Now, let’s create a custom domain together 🤩

This process is quite different depending on your operating system.

Step 1: Open your terminal

This is how my terminal looks

Step 2: Edit the HOSTS file in the terminal

sudo nano /etc/hosts

You may be required to enter your password. So, enter it if you’re prompted to do so.

Opening the HOSTS file

After typing your password, the nano text editor will open the HOSTS file.

This is how the HOSTS file looks

Step 3: Add your custom domain to the HOSTS file

Type 127.0.0.1 testwebsite.com at the bottom of the file. You should replace testwebsite.com with your own domain.

Add your custom domain to the HOSTS file

Now, we need to save our changes and exit. To do this, press Ctrl + X, then press Y to save the file.

Save your changes and exit

Step 4: Install a web server (skip if you already have one)

We’ll be using the webserver to manage virtual hosts. The most popular ones are Nginx and Apache.

For Linux:

sudo apt-get update
sudo apt-get install nginx

If you prefer Apache,

sudo apt-get install apache2

Installing Nginx

For macOS, follow the instructions here: https://www.javatpoint.com/installing-nginx-on-mac

Step 5: Configure the virtual hosts

Let’s open the web server’s config file and do some magic.

If you’re using macOS, run this in your terminal (Nginx):

sudo nano /usr/local/etc/nginx/nginx.conf

If you’re using Apache, follow this article: https://medium.com/@JanFaessler/create-vhosts-for-multiple-local-urls-with-homebrew-apache2-httpd-97d4ec59e125

If you’re using a Linux OS,

Nginx:

sudo nano /etc/nginx/sites-available/default.conf

Apache:

sudo nano /etc/apache2/sites-available/000-default.conf

After opening it, modify the file to the following:

If you’re using Nginx,

server {
    listen 80;
    listen [::]:80;
    server_name testwebsite.com www.testwebsite.com;
    access_log /var/log/nginx/mysite.com.access.log;
    error_log /var/log/nginx/mysite.com.error.log;
    location / {
        proxy_pass http://127.0.0.1:3000;       
        proxy_http_version 1.1;        
        proxy_set_header Upgrade $http_upgrade;               
        proxy_set_header Connection ‘upgrade’;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

If you’re using Apache,

<VirtualHost *:80>
    ServerName testwebsite.com
    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
</VirtualHost>

We set the proxy_pass to http://127.0.0.1:3000 because my app is running on 3000. So, you should change it if your app runs on another port.

Restart your web server for the changes to take effect

Yay! We’re done 🥳

You’ve created a custom domain for your local apps. To visit your app on the browser, you would simply type testwebsite.com (without the port).

Also, if you have another port running locally, you can still use your custom domain but you’ll have to attach the port. e.g mysite.com:8000.

If you have any issue or want to contact me, my Twitter is open.