keepcalculator

06 Numbers and Powers

Nginx Subdomain Setup: Step-by-Step Guide

Card No. 06·74086 · Updated · Standard formula, shown below

This guide walks you through setting up a subdomain on an Nginx server, so you can host a separate site or app at something like blog.example.com or api.example.com. You’ll create a server block (virtual host) that listens for that subdomain and points to its own document root. The process involves editing Nginx configuration files, creating a directory for the subdomain’s files, and reloading Nginx.

What You’ll Need

  • A server with Nginx installed and running (Ubuntu/Debian, CentOS/RHEL, or similar).
  • Root or sudo access to edit configuration files and reload Nginx.
  • Your domain’s DNS management panel (from your registrar or DNS provider) to create an A record for the subdomain.
  • Basic familiarity with the command line and a text editor (nano, vim, etc.).

Step-by-Step

  1. Create the DNS record for your subdomain. Log in to your DNS provider and add an A record. For example, for sub.example.com, set the host to sub and the value to your server’s public IP address. Wait for DNS propagation (can take from minutes to a few hours).
  2. Create the document root directory. This is where your subdomain’s files will live. For example: sudo mkdir -p /var/www/sub.example.com/public_html. Adjust the path to match your preference.
  3. Add a test file. Create index.html in that directory with a simple message like <h1>Subdomain works!</h1> to verify later.
  4. Create a new server block file. In Nginx, each site is defined in a file under /etc/nginx/sites-available/ (on Debian/Ubuntu) or /etc/nginx/conf.d/ (on RHEL/CentOS). Use a name like sub.example.com. Example: sudo nano /etc/nginx/sites-available/sub.example.com.
  5. Write the server block configuration. Paste the following, replacing sub.example.com with your actual subdomain and the root path with the directory you created:
    server {
        listen 80;
        server_name sub.example.com;
    
        root /var/www/sub.example.com/public_html;
        index index.html index.htm;
    
        location / {
            try_files $uri $uri/ =404;
        }
    }
        
  6. Enable the site. On Debian/Ubuntu, create a symlink from sites-available to sites-enabled: sudo ln -s /etc/nginx/sites-available/sub.example.com /etc/nginx/sites-enabled/. On RHEL/CentOS, the file is already active in conf.d.
  7. Test the configuration. Run sudo nginx -t. If you see “syntax is ok” and “test is successful”, you’re good. If there are errors, fix them before continuing.
  8. Reload Nginx. Apply the changes with sudo systemctl reload nginx (or sudo service nginx reload on older systems).
  9. Verify. Open a browser and go to http://sub.example.com. You should see your test page. If not, check DNS propagation and try again in a few minutes.

Common Mistakes

  • Forgetting the trailing dot in DNS. Some DNS providers require a trailing dot (e.g., sub.example.com.). Check your provider’s documentation.
  • Using the wrong server_name. The server_name must match the subdomain exactly, including case (though Nginx is case-insensitive for hostnames).
  • Not enabling the site. On Debian/Ubuntu, forgetting the symlink means Nginx won’t load the config, and you’ll get a default page or 404.
  • Forgetting to reload Nginx. Editing config files does nothing until you reload or restart the service.
  • Incorrect file permissions. If the web server user (often www-data) can’t read the files, you’ll get a 403 Forbidden error. Ensure the directory and files are readable: sudo chown -R www-data:www-data /var/www/sub.example.com.

Tips

  • Use a dedicated server block for each subdomain. This isolates configurations and makes management easier.
  • Start with HTTP. Once working, you can add HTTPS using Let’s Encrypt (certbot) for free SSL certificates.
  • Keep your configs in version control. If you make a mistake, you can easily revert.
  • Use nginx -t before reloading. This catches syntax errors that could take down your entire site.
  • For wildcard subdomains, you can use server_name *.example.com; but be careful—it catches all subdomains, which may not be intended.

Troubleshooting

  • Site not loading at all: Check if DNS has propagated using dig sub.example.com or an online DNS checker. If the IP is wrong, fix the A record.
  • Getting the default Nginx page: This usually means the server block isn’t being used. Check that the server_name matches and that the symlink exists (if applicable).
  • 404 Not Found: The server block is active, but the file doesn’t exist. Verify the root path and that index.html is in that directory.
  • 403 Forbidden: Permission issue. Check file permissions and ensure the web server user can traverse the directory. Also check for a deny all; directive in the config.
  • 502 Bad Gateway: If you’re proxying to a backend (like a Node.js app), the backend isn’t running or the proxy_pass URL is wrong. Ensure the service is up.
  • Configuration test fails: Read the error message. It usually points to the exact line number with the issue (e.g., missing semicolon).

Frequently Asked Questions

Do I need to create a separate DNS record for each subdomain?

Yes, unless you use a wildcard record (*), which points all subdomains to one IP. Wildcards are convenient but less flexible if you need different IPs.

Can I use the same document root for multiple subdomains?

Yes, you can point different server blocks to the same root. This is often done for redirects or to serve the same content under different names.

How do I set up an SSL certificate for my subdomain?

Use Certbot: sudo certbot --nginx -d sub.example.com. It will automatically obtain and install a certificate, and set up automatic renewal.

What if I want to run a different app (e.g., Node.js) on the subdomain?

Instead of a static root, use a location / { proxy_pass http://localhost:3000; } block to forward requests to your app running on a local port.

Can I set up a subdomain without changing DNS?

No. The subdomain must resolve to your server’s IP via DNS. You can test locally by editing your /etc/hosts file, but that only works on your machine.

How long does DNS propagation take?

It can take from a few minutes to 48 hours, though usually it’s under an hour. Check with dig or an online tool to see if it has propagated.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →