Running a Subdomain on localhost: A Step-by-Step Guide

Pawan Kumar
3 min readOct 6, 2023

--

Running a subdomain on your localhost is a common practice for web developers and designers. It allows you to develop and test various parts of your website locally without affecting your live site. In this step-by-step guide, we’ll show you how to set up and run a subdomain on your localhost.

Table of Contents
Introduction
Prerequisites
Step 1: Edit Hosts File
Step 2: Configure Virtual Hosts
Step 3: Restart Your Server
Step 4: Access Your Subdomain
Conclusion

1. Introduction

A subdomain is a part of your main domain that can be used to host separate websites or sections of your site. Running a subdomain locally is useful for testing new features, making updates, or creating a development environment that mirrors your live site.

2. Prerequisites

Before you begin, make sure you have the following:

  • A web server (e.g., Apache, Nginx) installed on your computer.
  • Basic knowledge of working with server configuration files.

3. Step 1: Edit Hosts File

For Windows:

  1. Open Notepad as an administrator (right-click and select “Run as administrator”).
  2. Go to File > Open and navigate to C:\Windows\System32\drivers\etc.
  3. Choose “All Files” in the file type dropdown.
  4. Open the hosts file.
  5. Add a new line at the end of the file, like this:
127.0.0.1    subdomain.localhost

For macOS and Linux:

  1. Open Terminal.
  2. Type sudo nano /etc/hosts and press Enter.
  3. Enter your system password.
  4. Add a new line at the end of the file, like this:
127.0.0.1    subdomain.localhost

Save the file and exit the text editor.

4. Step 2: Configure Virtual Hosts

Now, you need to configure your web server to recognize the subdomain. Below are instructions for Apache and Nginx:

For Apache:

  1. Navigate to your Apache configuration directory. For example, /etc/apache2/sites-available on Linux.
  2. Create a new configuration file for your subdomain, e.g., subdomain.localhost.conf.
  3. Add the following configuration:
<VirtualHost *:80>
ServerAdmin webmaster@localhost
ServerName subdomain.localhost
DocumentRoot /path/to/your/website/root

<Directory /path/to/your/website/root>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>

ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
  1. Save the file and exit the text editor.
  2. Enable the new site with the command sudo a2ensite subdomain.localhost.conf.
  3. Reload Apache with sudo systemctl reload apache2 (or sudo service apache2 reload).

For Nginx:

  1. Navigate to your Nginx configuration directory. For example, /etc/nginx/sites-available on Linux.
  2. Create a new configuration file for your subdomain, e.g., subdomain.localhost.
  3. Add the following configuration:
server {
listen 80;
server_name subdomain.localhost;
root /path/to/your/website/root;

location / {
index index.html index.htm index.php;
try_files $uri $uri/ /index.php?$args;
}

error_log /var/log/nginx/error.log;
access_log /var/log/nginx/access.log;
}
  1. Save the file and exit the text editor.
  2. Create a symbolic link to enable the site: sudo ln -s /etc/nginx/sites-available/subdomain.localhost /etc/nginx/sites-enabled/.
  3. Test your Nginx configuration with sudo nginx -t and then reload Nginx: sudo systemctl reload nginx (or sudo service nginx reload).

5. Step 3: Restart Your Server

Restart your web server to apply the changes:

  • For Apache: sudo systemctl restart apache2 (or sudo service apache2 restart).
  • For Nginx: sudo systemctl restart nginx (or sudo service nginx restart).

6. Step 4: Access Your Subdomain

Open your web browser and enter http://subdomain.localhost in the address bar. You should see your website or the content you placed in the subdomain's root directory.

7. Conclusion

Running a subdomain on your localhost is a valuable practice for web development and testing. It allows you to work on different parts of your site separately and efficiently. By following this guide, you can set up and run a subdomain on your local development environment with ease.

--

--