To route a subdomain to your PM2-managed Node.js application on Ubuntu, you must configure Nginx as a reverse proxy. This involves creating a specific server block that listens on port 80 or 443 and forwards incoming HTTP requests to the local port where your PM2 process is running. Proper DNS configuration for the subdomain is also required to ensure traffic reaches your server.
Prerequisites and DNS Configuration
Before modifying Nginx configurations, ensure your domain registrar or DNS provider has an A record (or CNAME) pointing your subdomain to your server's public IP address. For example, if you want
app.example.com, create a record for
app pointing to your VPS IP. Allow time for DNS propagation, which can take up to 48 hours, though it often resolves within minutes.
You need root or sudo access to your Ubuntu server. Ensure Nginx is installed and running. If you are using a firewall like UFW, make sure ports 80 (HTTP) and 443 (HTTPS) are open. Your PM2 application should already be running on a specific port, such as 3000 or 8080. You can verify this by checking your PM2 status with the command
pm2 list.
Creating the Nginx Server Block
Nginx stores site configurations in the
/etc/nginx/sites-available/ directory. Create a new file named after your subdomain, for instance,
app.example.com. Use a text editor like
nano to write the configuration.
server {
listen 80;
server_name app.example.com;
location / {
proxy_pass http://localhost: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;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Replace
app.example.com with your actual subdomain name. The critical directive is
proxy_pass, which must point to the exact URL and port where your PM2 app is listening. If your app runs on port 3000, use
http://localhost:3000. The headers included ensure that WebSocket connections work correctly, which is essential for real-time applications like Meteor or chat apps.
Enabling the Site and Testing Configuration
After saving the file, you must enable the site by creating a symbolic link from
sites-available to
sites-enabled. Run the following command:
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
It is crucial to test your Nginx syntax before restarting the service. Any typo in the configuration file will prevent Nginx from starting. Use the test command:
sudo nginx -t
If the output says
syntax is ok and
test is successful, you can reload Nginx to apply the changes. If you see errors, edit the file again and correct them. Reloading ensures existing connections are handled gracefully while applying the new config.
sudo systemctl reload nginx
At this point, visiting your subdomain should display your PM2 application. If you encounter issues, check the Nginx error log at
/var/log/nginx/error.log for details. For more troubleshooting tips on gateway errors, refer to our guide on
Troubleshooting React/Express on Nginx/Ubuntu.
Securing with SSL/TLS
Running over plain HTTP is insecure and may be blocked by modern browsers. Install Certbot to automatically obtain and renew free SSL certificates from Let's Encrypt. On Ubuntu, install Certbot and the Nginx plugin:
sudo apt update
sudo apt install certbot python3-certbot-nginx
Run Certbot with your domain name. It will automatically detect your Nginx server block and modify it to include SSL settings.
sudo certbot --nginx -d app.example.com
Certbot will ask for your email and agree to terms. It will then fetch the certificate and redirect all HTTP traffic to HTTPS. Verify the setup by visiting
https://app.example.com. Look for the padlock icon in your browser address bar. If you manage multiple domains, consider reading about
Setting up Nginx Traffic Redirect for Subdomains on VPS with Multiple Docker Containers and Cloudflare to understand broader routing strategies.
Maintaining and Troubleshooting
Regularly check your PM2 logs to ensure the application is responding correctly. Use
pm2 logs to view recent activity. If the site returns a 502 Bad Gateway, Nginx cannot connect to your backend. Ensure your PM2 process is actually running and listening on the specified port. Sometimes, services crash silently; restart your app with
pm2 restart all and check if the issue persists.
Also, monitor disk space and memory usage. Nginx itself is lightweight, but logging can fill up disks quickly. Configure log rotation if necessary. Avoid leaving default Nginx pages active, as they can expose version information. If you have removed Nginx previously and still see errors, check for residual configurations as discussed in
Why is my domain URL still rendering a 404 page after uninstalling nginx?.
Frequently Asked Questions
What if I get a 502 Bad Gateway error?
This usually means Nginx cannot reach your PM2 app. Check if your app is running with
pm2 list and verify the port matches the
proxy_pass directive. Restart your PM2 process if it appears stopped or unresponsive.
Can I host multiple PM2 apps on different subdomains?
Yes, create separate server blocks for each subdomain in
sites-available. Each block should point to a different local port where a distinct PM2 ecosystem file manages its respective application.
Do I need to restart Nginx after changing PM2 ports?
No, you only need to reload Nginx (
systemctl reload nginx) when updating Nginx config files. However, if you change the port your PM2 app listens on, you must update the
proxy_pass line in your Nginx config and then reload Nginx.
How do I force HTTPS for my subdomain?
Certbot handles this automatically by adding
return 301 https://$server_name$request_uri; to the HTTP server block. If you did not use Certbot, manually add this redirect rule inside the
listen 80 server block.
Why is my subdomain showing the default Nginx page?
This happens if the server block is not enabled or has a syntax error. Ensure the symlink exists in
sites-enabled and run
nginx -t to confirm there are no configuration errors preventing the new block from loading.