<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Saurabh Bag</title>
    <description>The latest articles on DEV Community by Saurabh Bag (@saurabh_bag_a104497accf47).</description>
    <link>https://dev.to/saurabh_bag_a104497accf47</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4245352%2F6f8e2b20-c107-48e5-8910-389ae8592dd5.png</url>
      <title>DEV Community: Saurabh Bag</title>
      <link>https://dev.to/saurabh_bag_a104497accf47</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/saurabh_bag_a104497accf47"/>
    <language>en</language>
    <item>
      <title>Deploy a Node.js API to Ubuntu with PM2, Nginx, MySQL and Let's Encrypt</title>
      <dc:creator>Saurabh Bag</dc:creator>
      <pubDate>Sun, 15 Nov 2026 04:18:25 +0000</pubDate>
      <link>https://dev.to/saurabh_bag_a104497accf47/deploy-a-nodejs-api-to-ubuntu-with-pm2-nginx-mysql-and-lets-encrypt-2lm6</link>
      <guid>https://dev.to/saurabh_bag_a104497accf47/deploy-a-nodejs-api-to-ubuntu-with-pm2-nginx-mysql-and-lets-encrypt-2lm6</guid>
      <description>&lt;p&gt;This is a complete guide to deploying a Node.js app to production on an Ubuntu server: PM2 to keep it running, Nginx as a reverse proxy, MySQL, and free SSL with Let's Encrypt and Certbot. Every step has a filled-in example, and the troubleshooting tables cover the errors that break most first deployments: the PM2 restart loop, &lt;code&gt;502 Bad Gateway&lt;/code&gt;, certbot &lt;code&gt;NXDOMAIN&lt;/code&gt;, and env files that crash the app on startup.&lt;/p&gt;

&lt;p&gt;It works on any Ubuntu VPS (22.04 or 24.04), on AWS EC2, DigitalOcean, Linode, Hetzner or any other host, and for any Node.js framework: Express, NestJS, Fastify or plain Node.&lt;/p&gt;

&lt;h2&gt;
  
  
  What you'll have at the end
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Your Node.js API running under &lt;strong&gt;PM2&lt;/strong&gt;, restarting on crashes and starting again after a server reboot&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Nginx&lt;/strong&gt; in front of it as a reverse proxy&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Free HTTPS (SSL certificate)&lt;/strong&gt; from Let's Encrypt, renewing automatically&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;MySQL&lt;/strong&gt; database with its own user&lt;/li&gt;
&lt;li&gt;A firewall that only lets in SSH, HTTP and HTTPS&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It works for any environment: staging, production, UAT or a fresh server.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to use this guide
&lt;/h2&gt;

&lt;p&gt;The stack is Node.js, PM2, Nginx, MySQL, Let's Encrypt and a DNS A record. Fill in the worksheet first. Each step then shows the command with &lt;code&gt;&amp;lt;placeholders&amp;gt;&lt;/code&gt;, followed by an example using the sample values below. Never write real secrets into notes or guides: keep them in a password manager.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Placeholder&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;th&gt;Example value used in this guide&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;app&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;App name, also the PM2 process name&lt;/td&gt;
&lt;td&gt;&lt;code&gt;orders-api&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;env&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Environment, the value of &lt;code&gt;NODE_ENV&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;staging&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;env-file&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Env file the app reads for &lt;code&gt;&amp;lt;env&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.env.staging&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;server-ip&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Server public IP (&lt;code&gt;curl -4 ifconfig.me&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;203.0.113.10&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;ssh-user&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Linux user that runs the app&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ubuntu&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;app-dir&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Folder the app lives in&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/home/ubuntu/orders-api&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;port&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Local port the app listens on; must be free&lt;/td&gt;
&lt;td&gt;&lt;code&gt;4000&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;api-domain&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Public domain for the API&lt;/td&gt;
&lt;td&gt;&lt;code&gt;api-staging.example.com&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;ui-origin&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Frontend URL allowed by CORS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;https://staging.example.com&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;git-host&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Git provider host&lt;/td&gt;
&lt;td&gt;&lt;code&gt;bitbucket.org&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;repo&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Repository path&lt;/td&gt;
&lt;td&gt;&lt;code&gt;acme/orders-api.git&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;branch&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Branch to deploy&lt;/td&gt;
&lt;td&gt;&lt;code&gt;main&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;node-version&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Node major version from &lt;code&gt;package.json&lt;/code&gt; &lt;code&gt;engines&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;24&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;&amp;lt;db-name&amp;gt;&lt;/code&gt; / &lt;code&gt;&amp;lt;db-user&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Database and its dedicated user&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;orders_staging&lt;/code&gt; / &lt;code&gt;orders_app&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;build-command&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Compiles the app&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm run build&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;migration-command&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Applies database migrations&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm run migration:run&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;seed-command&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Creates first-login data&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm run seed:admin&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;start-file&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Compiled entry file&lt;/td&gt;
&lt;td&gt;&lt;code&gt;dist/server.js&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;health-path&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Health-check URL path&lt;/td&gt;
&lt;td&gt;&lt;code&gt;api/v1/health&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Before starting, find your app's real values for the last six rows in its README or &lt;code&gt;package.json&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before you start
&lt;/h2&gt;

&lt;p&gt;Most setup delays come from missing access or missing values, not from the commands. Collect these before you touch the server.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;SSH access to the server, and an SFTP client such as FileZilla as a fallback&lt;/li&gt;
&lt;li&gt;Admin on the git repository, to add a read-only deploy (access) key for the server&lt;/li&gt;
&lt;li&gt;Access to the DNS provider for the domain (for example AWS Route 53), to add the A record&lt;/li&gt;
&lt;li&gt;Access to the server firewall or cloud security group, with ports 22, 80 and 443 open&lt;/li&gt;
&lt;li&gt;Database admin access on the server, to create the database and its user&lt;/li&gt;
&lt;li&gt;A free port: &lt;code&gt;sudo ss -ltnp | grep &amp;lt;port&amp;gt;&lt;/code&gt; prints nothing&lt;/li&gt;
&lt;li&gt;The app's full list of environment variables (usually &lt;code&gt;.env.example&lt;/code&gt;), with a value for every required one&lt;/li&gt;
&lt;li&gt;New random secrets for this environment, each from &lt;code&gt;openssl rand -hex 32&lt;/code&gt;; never reuse another environment's secrets&lt;/li&gt;
&lt;li&gt;Credentials for every third-party service the app calls in this environment (cloud storage, SMS, email, CAPTCHA, payment and so on), or a decision to use the app's fake provider where it allows one&lt;/li&gt;
&lt;li&gt;Seed data the app needs for its first login, such as an admin user&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step-by-step setup
&lt;/h2&gt;

&lt;p&gt;Do the steps in order: each needs the one before it. DNS must resolve before HTTPS, and the env file must pass the app's checks before PM2 runs it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 1. Install Node.js, PM2, Nginx and MySQL on Ubuntu
&lt;/h3&gt;

&lt;p&gt;Skip what is already installed. Check with &lt;code&gt;node -v&lt;/code&gt;, &lt;code&gt;pm2 -v&lt;/code&gt;, &lt;code&gt;nginx -v&lt;/code&gt; and &lt;code&gt;mysql --version&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh &lt;span class="o"&gt;|&lt;/span&gt; bash
&lt;span class="nb"&gt;source&lt;/span&gt; ~/.bashrc
nvm install &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;node-version&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
npm install -g pm2
sudo apt update
sudo apt install -y git nginx mysql-server certbot python3-certbot-nginx
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;nvm install 24
node -v        &lt;span class="c"&gt;# v24.x.x&lt;/span&gt;
pm2 -v         &lt;span class="c"&gt;# 6.x.x&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 2. Create the MySQL database and user
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;DATABASE&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="kt"&gt;CHARACTER&lt;/span&gt; &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;utf8mb4&lt;/span&gt; &lt;span class="k"&gt;COLLATE&lt;/span&gt; &lt;span class="n"&gt;utf8mb4_0900_ai_ci&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="no"&gt;USER&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;db-user&amp;gt;'&lt;/span&gt;@&lt;span class="s1"&gt;'localhost'&lt;/span&gt; &lt;span class="no"&gt;IDENTIFIED&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;strong-password&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;GRANT&lt;/span&gt; &lt;span class="k"&gt;ALL&lt;/span&gt; &lt;span class="no"&gt;PRIVILEGES&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;TO&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;db-user&amp;gt;'&lt;/span&gt;@&lt;span class="s1"&gt;'localhost'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="no"&gt;FLUSH&lt;/span&gt; &lt;span class="no"&gt;PRIVILEGES&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt; open MySQL with &lt;code&gt;sudo mysql&lt;/code&gt;, then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;DATABASE&lt;/span&gt; &lt;span class="n"&gt;orders_staging&lt;/span&gt; &lt;span class="kt"&gt;CHARACTER&lt;/span&gt; &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;utf8mb4&lt;/span&gt; &lt;span class="k"&gt;COLLATE&lt;/span&gt; &lt;span class="n"&gt;utf8mb4_0900_ai_ci&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="no"&gt;USER&lt;/span&gt; &lt;span class="s1"&gt;'orders_app'&lt;/span&gt;@&lt;span class="s1"&gt;'localhost'&lt;/span&gt; &lt;span class="no"&gt;IDENTIFIED&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;output of: openssl rand -base64 24&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;GRANT&lt;/span&gt; &lt;span class="k"&gt;ALL&lt;/span&gt; &lt;span class="no"&gt;PRIVILEGES&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;orders_staging&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;TO&lt;/span&gt; &lt;span class="s1"&gt;'orders_app'&lt;/span&gt;@&lt;span class="s1"&gt;'localhost'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="no"&gt;FLUSH&lt;/span&gt; &lt;span class="no"&gt;PRIVILEGES&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="no"&gt;EXIT&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The app never connects as &lt;code&gt;root&lt;/code&gt;. The user is created for &lt;code&gt;localhost&lt;/code&gt;, so set the app's DB host to &lt;code&gt;localhost&lt;/code&gt;: MySQL may not match it for a TCP connection to &lt;code&gt;127.0.0.1&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 3. Add a deploy key so the server can pull from GitHub or Bitbucket
&lt;/h3&gt;

&lt;p&gt;Without this, &lt;code&gt;git clone&lt;/code&gt; and &lt;code&gt;git pull&lt;/code&gt; fail with &lt;code&gt;Permission denied (publickey)&lt;/code&gt;. Use one key per repository, so this app's key never affects other apps on the server.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ssh-keygen -t ed25519 -C &lt;span class="s2"&gt;"&amp;lt;env&amp;gt;-&amp;lt;app&amp;gt;"&lt;/span&gt; -f ~/.ssh/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; -N &lt;span class="s2"&gt;""&lt;/span&gt;
cat ~/.ssh/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;.pub
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Add the printed public key to the repository as a read-only key. In Bitbucket: Repository settings, Access keys. In GitHub: Settings, Deploy keys. Then add a host alias to &lt;code&gt;~/.ssh/config&lt;/code&gt;, lock the files down and test.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ssh-keygen -t ed25519 -C &lt;span class="s2"&gt;"staging-orders-api"&lt;/span&gt; -f ~/.ssh/orders-api -N &lt;span class="s2"&gt;""&lt;/span&gt;
cat ~/.ssh/orders-api.pub
&lt;span class="c"&gt;# ssh-ed25519 AAAAC3Nza...  staging-orders-api   &amp;lt;- paste this into Bitbucket&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;~/.ssh/config&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ssh"&gt;&lt;code&gt;&lt;span class="nc"&gt;Host&lt;/span&gt; &lt;span class="n"&gt;git&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;orders&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;
    &lt;span class="nc"&gt;HostName&lt;/span&gt; &lt;span class="n"&gt;bitbucket&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;org&lt;/span&gt;
    &lt;span class="nc"&gt;User&lt;/span&gt; &lt;span class="n"&gt;git&lt;/span&gt;
    &lt;span class="nc"&gt;IdentityFile&lt;/span&gt; &lt;span class="o"&gt;~/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ssh&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;orders&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;
    &lt;span class="nc"&gt;IdentitiesOnly&lt;/span&gt; &lt;span class="n"&gt;yes&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;chmod 600 ~/.ssh/config ~/.ssh/orders-api
ssh -T git@git-orders-api
&lt;span class="c"&gt;# authenticated via a deploy key.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 4. Clone the code onto the server
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone git@git-&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;:&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;repo&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
git checkout &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;branch&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
npm ci
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone git@git-orders-api:acme/orders-api.git /home/ubuntu/orders-api
&lt;span class="nb"&gt;cd&lt;/span&gt; /home/ubuntu/orders-api
git checkout main
npm ci
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No repository access yet? Upload &lt;code&gt;src/&lt;/code&gt;, &lt;code&gt;package.json&lt;/code&gt;, &lt;code&gt;package-lock.json&lt;/code&gt;, the build config and &lt;code&gt;ecosystem.config.cjs&lt;/code&gt; with SFTP (for example FileZilla) to &lt;code&gt;/home/ubuntu/orders-api&lt;/code&gt;. Then check the files landed where expected: &lt;code&gt;ls /home/ubuntu/orders-api/src&lt;/code&gt; must list the source files, not another &lt;code&gt;src&lt;/code&gt; folder.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 5. Create the production .env file
&lt;/h3&gt;

&lt;p&gt;The env file never goes through git. Create it on the server, or upload it with SFTP, then lock it down. Start from the app's &lt;code&gt;.env.example&lt;/code&gt; and follow the Env file rules section below.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;nano &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;env-file&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
chmod 600 &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;env-file&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;nano /home/ubuntu/orders-api/.env.staging
chmod 600 /home/ubuntu/orders-api/.env.staging
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight conf"&gt;&lt;code&gt;&lt;span class="na"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;staging&lt;/span&gt;
&lt;span class="na"&gt;PORT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;4000&lt;/span&gt;
&lt;span class="na"&gt;CORS_ORIGIN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//staging.example.com&lt;/span&gt;
&lt;span class="na"&gt;TRUST_PROXY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;

&lt;span class="na"&gt;DB_HOST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;localhost&lt;/span&gt;
&lt;span class="na"&gt;DB_PORT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;3306&lt;/span&gt;
&lt;span class="na"&gt;DB_USERNAME&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;orders_app&lt;/span&gt;
&lt;span class="na"&gt;DB_PASSWORD&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;password&lt;/span&gt; &lt;span class="n"&gt;from&lt;/span&gt; &lt;span class="n"&gt;step&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="na"&gt;DB_DATABASE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;orders_staging&lt;/span&gt;

&lt;span class="na"&gt;JWT_SECRET&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="n"&gt;of&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;openssl&lt;/span&gt; &lt;span class="n"&gt;rand&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;hex&lt;/span&gt; &lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;

&lt;span class="na"&gt;SMS_PROVIDER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;fake&lt;/span&gt;
&lt;span class="c1"&gt;# SMS_API_KEY=
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The last two lines show rule 2 below: an unused key is commented out, not left blank.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 6. Build the app and run database migrations
&lt;/h3&gt;

&lt;p&gt;Prefix every server command with &lt;code&gt;NODE_ENV=&amp;lt;env&amp;gt;&lt;/code&gt;. Without it, the app may read the wrong env file or the wrong database. Take a database backup first if the database already holds data.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;build-command&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;env&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;migration-command&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;env&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;seed-command&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /home/ubuntu/orders-api
npm run build
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;staging npm run migration:run
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;staging npm run seed:admin
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 7. Keep the Node.js app running with PM2 (and start it on reboot)
&lt;/h3&gt;

&lt;p&gt;A hand run shows any startup error directly, instead of hiding it in a PM2 restart loop. Wait for the app's "listening" line, then press Ctrl+C.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;env&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; node &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;start-file&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /home/ubuntu/orders-api
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;staging node dist/server.js
&lt;span class="c"&gt;# orders-api listening on port 4000 (staging)   &amp;lt;- press Ctrl+C&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then start it under PM2, from the app folder. If the app has no &lt;code&gt;ecosystem.config.cjs&lt;/code&gt;, create one:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;module&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;exports&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apps&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;app&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;script&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'./&amp;lt;start-file&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;cwd&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;__dirname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;autorestart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;max_restarts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;restart_delay&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;5000&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;max_memory_restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'512M'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;env_&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="no"&gt;NODE_ENV&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&amp;lt;env&amp;gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;PORT&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;port&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
pm2 start ecosystem.config.cjs --env &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;env&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
pm2 save
pm2 startup
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;module&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;exports&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apps&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'orders-api'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;script&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'./dist/server.js'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;cwd&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;__dirname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;autorestart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;max_restarts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;restart_delay&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;5000&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;max_memory_restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'512M'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;env_staging&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="no"&gt;NODE_ENV&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'staging'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;PORT&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;4000&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /home/ubuntu/orders-api
pm2 start ecosystem.config.cjs --env staging
pm2 save
pm2 startup     &lt;span class="c"&gt;# then run the sudo command it prints&lt;/span&gt;
pm2 list        &lt;span class="c"&gt;# orders-api  online  restarts 0  mem 95mb&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In &lt;code&gt;pm2 list&lt;/code&gt;, the restart count must stay at 0 and memory must be above 0.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 8. Point your domain to the server (DNS A record)
&lt;/h3&gt;

&lt;p&gt;At the DNS provider, create an A record from the API domain to the server IP, then wait until it resolves. In Route 53, use simple routing with alias off. In Cloudflare, set it to "DNS only" until HTTPS works.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Field&lt;/th&gt;
&lt;th&gt;Value&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Type&lt;/td&gt;
&lt;td&gt;&lt;code&gt;A&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Name&lt;/td&gt;
&lt;td&gt;subdomain part of &lt;code&gt;&amp;lt;api-domain&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Value&lt;/td&gt;
&lt;td&gt;&lt;code&gt;&amp;lt;server-ip&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TTL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;300&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;nslookup &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;api-domain&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; 8.8.8.8
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt; in the &lt;code&gt;example.com&lt;/code&gt; zone, add type &lt;code&gt;A&lt;/code&gt;, name &lt;code&gt;api-staging&lt;/code&gt;, value &lt;code&gt;203.0.113.10&lt;/code&gt;, TTL &lt;code&gt;300&lt;/code&gt;. Then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -4 ifconfig.me                          &lt;span class="c"&gt;# 203.0.113.10  (run on the server)&lt;/span&gt;
nslookup api-staging.example.com 8.8.8.8
&lt;span class="c"&gt;# Name:    api-staging.example.com&lt;/span&gt;
&lt;span class="c"&gt;# Address: 203.0.113.10&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 9. Configure Nginx as a reverse proxy for Node.js
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo nano /etc/nginx/sites-available/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;api-domain&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;80&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;server_name&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;domain&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;client_max_body_size&lt;/span&gt; &lt;span class="mi"&gt;60M&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//127.0.0.1:&amp;lt;port&amp;gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Real&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="no"&gt;IP&lt;/span&gt; $&lt;span class="n"&gt;remote_addr&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;For&lt;/span&gt; $&lt;span class="n"&gt;proxy_add_x_forwarded_for&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; $&lt;span class="n"&gt;scheme&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ln -s /etc/nginx/sites-available/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;api-domain&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt; &lt;code&gt;/etc/nginx/sites-available/api-staging.example.com&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;80&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;server_name&lt;/span&gt; &lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;staging&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;client_max_body_size&lt;/span&gt; &lt;span class="mi"&gt;60M&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//127.0.0.1:4000;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Real&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="no"&gt;IP&lt;/span&gt; $&lt;span class="n"&gt;remote_addr&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;For&lt;/span&gt; $&lt;span class="n"&gt;proxy_add_x_forwarded_for&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Forwarded&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Proto&lt;/span&gt; $&lt;span class="n"&gt;scheme&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ln -s /etc/nginx/sites-available/api-staging.example.com /etc/nginx/sites-enabled/
sudo nginx -t
&lt;span class="c"&gt;# nginx: configuration file /etc/nginx/nginx.conf test is successful&lt;/span&gt;
sudo systemctl reload nginx
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Reload only when &lt;code&gt;nginx -t&lt;/code&gt; reports success. Set &lt;code&gt;client_max_body_size&lt;/code&gt; above the app's largest upload. Behind Nginx, the app must trust one proxy hop (in Express: &lt;code&gt;app.set('trust proxy', 1)&lt;/code&gt;), or rate limits and client IPs will be wrong.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 10. Add free SSL with Let's Encrypt and Certbot
&lt;/h3&gt;

&lt;p&gt;Run this only after step 8 resolves. Certbot gets the certificate, edits the Nginx site, adds the HTTP-to-HTTPS redirect and schedules renewal.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo certbot --nginx -d &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;api-domain&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
sudo certbot renew --dry-run
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo certbot --nginx -d api-staging.example.com
&lt;span class="c"&gt;# Successfully received certificate.&lt;/span&gt;
&lt;span class="c"&gt;# Successfully deployed certificate for api-staging.example.com&lt;/span&gt;
sudo certbot renew --dry-run
&lt;span class="c"&gt;# Congratulations, all simulated renewals succeeded&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Step 11. Secure the server with the UFW firewall
&lt;/h3&gt;

&lt;p&gt;Only SSH, HTTP and HTTPS stay open. Never open the app port or the database port to the internet: Nginx is the only way in.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;sudo ufw allow OpenSSH
sudo ufw allow &lt;span class="s1"&gt;'Nginx Full'&lt;/span&gt;
sudo ufw &lt;span class="nb"&gt;enable&lt;/span&gt;
sudo ufw status
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt; &lt;code&gt;sudo ufw status&lt;/code&gt; on a correct server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Status: active
To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
Nginx Full                 ALLOW       Anywhere
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Port &lt;code&gt;4000&lt;/code&gt; and port &lt;code&gt;3306&lt;/code&gt; must not appear in the list. If the server also has a cloud security group, allow only 22, 80 and 443 there too.&lt;/p&gt;

&lt;h2&gt;
  
  
  Env file rules
&lt;/h2&gt;

&lt;p&gt;A wrong env file is the most common reason a new server fails: the app exits at startup, and PM2 restarts it in a loop. These rules apply to every app and environment.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Rule&lt;/th&gt;
&lt;th&gt;Example&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;1. One file per environment, picked by &lt;code&gt;NODE_ENV&lt;/code&gt;.&lt;/strong&gt; Run every command from the folder that holds the file.&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;NODE_ENV=staging&lt;/code&gt; reads &lt;code&gt;.env.staging&lt;/code&gt;; &lt;code&gt;NODE_ENV=production&lt;/code&gt; reads &lt;code&gt;.env.production&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;2. Blank is not the same as missing.&lt;/strong&gt; An empty value is an empty string, which strict validation rejects.&lt;/td&gt;
&lt;td&gt;Wrong: &lt;code&gt;SMS_API_KEY=&lt;/code&gt; · Right: &lt;code&gt;# SMS_API_KEY=&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;3. A real provider needs its credentials.&lt;/strong&gt; Switching a service from fake to real makes its keys required.&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;SMS_PROVIDER=twilio&lt;/code&gt; also needs &lt;code&gt;SMS_API_KEY&lt;/code&gt; and &lt;code&gt;SMS_SENDER&lt;/code&gt;; &lt;code&gt;SMS_PROVIDER=fake&lt;/code&gt; needs neither&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;4. Env files stay out of git.&lt;/strong&gt; Keep them on the server with &lt;code&gt;chmod 600&lt;/code&gt;, and in a password manager. If one is committed, change every secret in it: git history keeps it.&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.gitignore&lt;/code&gt; holds &lt;code&gt;.env.*&lt;/code&gt; and &lt;code&gt;!.env.example&lt;/code&gt;; &lt;code&gt;ls -l .env.staging&lt;/code&gt; shows &lt;code&gt;-rw-------&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;5. Each environment gets its own secrets.&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Staging &lt;code&gt;JWT_SECRET&lt;/code&gt; and production &lt;code&gt;JWT_SECRET&lt;/code&gt; are two separate &lt;code&gt;openssl rand -hex 32&lt;/code&gt; outputs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;6. An encryption key is permanent.&lt;/strong&gt; Changing it later makes data already encrypted with it unreadable.&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;DATA_ENCRYPTION_KEY&lt;/code&gt; once, before the first real record is saved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;7. Paired settings change together.&lt;/strong&gt; Where the frontend and the API share a setting, change both.&lt;/td&gt;
&lt;td&gt;API &lt;code&gt;CORS_ORIGIN=https://staging.example.com&lt;/code&gt; and frontend &lt;code&gt;VITE_API_URL=https://api-staging.example.com&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;8. Restart after every change.&lt;/strong&gt; A frontend setting needs a rebuild instead, because build tools bake it into the bundle.&lt;/td&gt;
&lt;td&gt;API: &lt;code&gt;pm2 restart orders-api --update-env&lt;/code&gt; · Frontend: &lt;code&gt;npm run build&lt;/code&gt; again, then deploy&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Verify the deployment
&lt;/h2&gt;

&lt;p&gt;Check from the inside out: the first check that fails tells you which layer to fix. Each example uses the sample values.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Check&lt;/th&gt;
&lt;th&gt;Example command&lt;/th&gt;
&lt;th&gt;Expected result&lt;/th&gt;
&lt;th&gt;If it fails&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1. App is running&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 list&lt;/code&gt;, twice, 10 seconds apart&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;orders-api&lt;/code&gt; online, restart count unchanged, memory above 0&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pm2 logs orders-api --err --lines 60 --nostream&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2. App answers locally&lt;/td&gt;
&lt;td&gt;&lt;code&gt;curl http://127.0.0.1:4000/api/v1/health&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;{"success":true,...}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;App or database: read the logs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3. DNS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;nslookup api-staging.example.com 8.8.8.8&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Address: 203.0.113.10&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Add or fix the A record (step 8)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4. HTTP through Nginx&lt;/td&gt;
&lt;td&gt;&lt;code&gt;curl -I http://api-staging.example.com/api/v1/health&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;301 Moved Permanently&lt;/code&gt; to HTTPS&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sudo nginx -t&lt;/code&gt;, the site file, port 80&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5. HTTPS&lt;/td&gt;
&lt;td&gt;&lt;code&gt;curl https://api-staging.example.com/api/v1/health&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Same as check 2&lt;/td&gt;
&lt;td&gt;certbot, port 443&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6. Frontend reaches the API&lt;/td&gt;
&lt;td&gt;Browser DevTools, Network tab, make a request&lt;/td&gt;
&lt;td&gt;Requests to &lt;code&gt;api-staging.example.com&lt;/code&gt; succeed&lt;/td&gt;
&lt;td&gt;Match the error in Troubleshooting&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;7. Survives a reboot (only on a server you may reboot)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sudo reboot&lt;/code&gt;, then &lt;code&gt;pm2 list&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;orders-api&lt;/code&gt; online&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 startup&lt;/code&gt;, then &lt;code&gt;pm2 save&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Troubleshooting common Node.js deployment errors
&lt;/h2&gt;

&lt;p&gt;Each row is a real problem from a past setup. Find your symptom, then apply the fix.&lt;/p&gt;

&lt;h3&gt;
  
  
  The app won't start
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Symptom&lt;/th&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;pm2 list&lt;/code&gt;: restart count climbing, blank status, &lt;code&gt;0b&lt;/code&gt; memory&lt;/td&gt;
&lt;td&gt;The app exits at startup; PM2 restarts it in a loop&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 logs &amp;lt;app&amp;gt; --err --lines 60 --nostream&lt;/code&gt;, fix what it names&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;pm2 reload&lt;/code&gt; or &lt;code&gt;pm2 restart&lt;/code&gt; says &lt;code&gt;Process &amp;lt;id&amp;gt; not found&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;The process is dead mid-restart&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 delete &amp;lt;app&amp;gt;&lt;/code&gt;, fix the cause, &lt;code&gt;pm2 start ecosystem.config.cjs --env &amp;lt;env&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;pm2 start&lt;/code&gt; crashes with &lt;code&gt;Cannot read properties of undefined (reading 'pm2_env')&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;PM2 is tripping over the crash-looping process&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 delete &amp;lt;app&amp;gt;&lt;/code&gt;, then start again&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Config error: &lt;code&gt;Too small: expected string to have &amp;gt;=1 characters&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;A variable is present but blank&lt;/td&gt;
&lt;td&gt;Comment the line out with &lt;code&gt;#&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Config error: &lt;code&gt;required when &amp;lt;PROVIDER&amp;gt;=...&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;A real provider is set without its credentials&lt;/td&gt;
&lt;td&gt;Fill the credentials, or use the fake provider where the environment allows it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Config error: &lt;code&gt;fake is not allowed in &amp;lt;env&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;The environment's safety rules refuse a fake provider, or the server runs an old build&lt;/td&gt;
&lt;td&gt;Use the real provider, or deploy the build that allows it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;EADDRINUSE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Another app already uses &lt;code&gt;&amp;lt;port&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;`sudo ss -ltnp \&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;{% raw %}&lt;code&gt;Cannot find module .../dist/server.js&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;No build on the server&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm ci &amp;amp;&amp;amp; npm run build&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;ECONNREFUSED ...:3306&lt;/code&gt; or &lt;code&gt;Access denied for user&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Database down or wrong credentials&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sudo systemctl status mysql&lt;/code&gt;; test with &lt;code&gt;mysql -u &amp;lt;db-user&amp;gt; -p &amp;lt;db-name&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Table ... doesn't exist&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Migrations not run&lt;/td&gt;
&lt;td&gt;&lt;code&gt;NODE_ENV=&amp;lt;env&amp;gt; npm run &amp;lt;migration-command&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Deploys that don't take effect
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Symptom&lt;/th&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;pm2 start ecosystem.config.cjs&lt;/code&gt; started a different app&lt;/td&gt;
&lt;td&gt;Run from the wrong folder, which held another app's ecosystem file&lt;/td&gt;
&lt;td&gt;Always &lt;code&gt;cd &amp;lt;app-dir&amp;gt;&lt;/code&gt; first&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;New source uploaded, nothing changed&lt;/td&gt;
&lt;td&gt;PM2 runs the compiled &lt;code&gt;dist/&lt;/code&gt;, not the source&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;npm run build&lt;/code&gt;, then &lt;code&gt;pm2 restart &amp;lt;app&amp;gt; --update-env&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Env change ignored&lt;/td&gt;
&lt;td&gt;PM2 kept the old environment&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 restart &amp;lt;app&amp;gt; --update-env&lt;/code&gt;, or delete and start again&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;git pull&lt;/code&gt; fails with &lt;code&gt;Permission denied (publickey)&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;The server has no key the repository accepts&lt;/td&gt;
&lt;td&gt;Add a deploy key (step 3); meanwhile upload with SFTP&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  The domain doesn't work
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Symptom&lt;/th&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Browser: &lt;code&gt;net::ERR_NAME_NOT_RESOLVED&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;No DNS record for the domain&lt;/td&gt;
&lt;td&gt;Add the A record (step 8)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;certbot: &lt;code&gt;DNS problem: NXDOMAIN looking up A&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;certbot ran before DNS resolved&lt;/td&gt;
&lt;td&gt;Wait for &lt;code&gt;nslookup&lt;/code&gt; to return the IP, run certbot again&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;certbot: timeout or connection error&lt;/td&gt;
&lt;td&gt;Port 80 is closed&lt;/td&gt;
&lt;td&gt;Open 80 and 443 in the firewall and security group&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;502 Bad Gateway&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Nginx is up but the app is not, or the port is wrong&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;pm2 list&lt;/code&gt;; check &lt;code&gt;proxy_pass&lt;/code&gt; uses &lt;code&gt;&amp;lt;port&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;413 Request Entity Too Large&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Upload is bigger than Nginx allows&lt;/td&gt;
&lt;td&gt;Raise &lt;code&gt;client_max_body_size&lt;/code&gt;, &lt;code&gt;nginx -t&lt;/code&gt;, reload&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Browser: CORS error&lt;/td&gt;
&lt;td&gt;The API doesn't allow the frontend's origin&lt;/td&gt;
&lt;td&gt;Set the app's CORS origin to &lt;code&gt;&amp;lt;ui-origin&amp;gt;&lt;/code&gt;, restart&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Frontend shows a blank page after deploy&lt;/td&gt;
&lt;td&gt;The frontend's own config check fails, for example a provider set with an empty key&lt;/td&gt;
&lt;td&gt;Fix the frontend env file and rebuild it&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Never run on a shared server:&lt;/strong&gt; &lt;code&gt;pm2 kill&lt;/code&gt; (stops every app), &lt;code&gt;pm2 delete all&lt;/code&gt;, or &lt;code&gt;sudo systemctl reload nginx&lt;/code&gt; without a passing &lt;code&gt;sudo nginx -t&lt;/code&gt; first.&lt;/p&gt;

&lt;h2&gt;
  
  
  Redeploying an update
&lt;/h2&gt;

&lt;p&gt;An update is pull, build, migrate, restart, check. Run it from the app folder.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app-dir&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
git pull
npm ci
&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;build-command&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;env&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;migration-command&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
pm2 restart &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; --update-env
pm2 logs &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;app&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; --lines 20 --nostream
curl https://&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;api-domain&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;health-path&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Example:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /home/ubuntu/orders-api
git pull
npm ci
npm run build
&lt;span class="nv"&gt;NODE_ENV&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;staging npm run migration:run
pm2 restart orders-api --update-env
pm2 logs orders-api --lines 20 --nostream
curl https://api-staging.example.com/api/v1/health
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Not every change needs every command:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What changed&lt;/th&gt;
&lt;th&gt;What to run&lt;/th&gt;
&lt;th&gt;Example&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Code only&lt;/td&gt;
&lt;td&gt;Pull, build, restart&lt;/td&gt;
&lt;td&gt;&lt;code&gt;git pull &amp;amp;&amp;amp; npm run build &amp;amp;&amp;amp; pm2 restart orders-api&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Dependencies (&lt;code&gt;package.json&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Add &lt;code&gt;npm ci&lt;/code&gt; before the build&lt;/td&gt;
&lt;td&gt;&lt;code&gt;git pull &amp;amp;&amp;amp; npm ci &amp;amp;&amp;amp; npm run build &amp;amp;&amp;amp; pm2 restart orders-api&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Database schema&lt;/td&gt;
&lt;td&gt;Back up, then migrate before the restart&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;mysqldump orders_staging &amp;gt; ~/backup-$(date +%F).sql&lt;/code&gt;, then &lt;code&gt;NODE_ENV=staging npm run migration:run&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Env file only&lt;/td&gt;
&lt;td&gt;Restart with &lt;code&gt;--update-env&lt;/code&gt;; no build&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pm2 restart orders-api --update-env&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nginx site&lt;/td&gt;
&lt;td&gt;Test, then reload&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sudo nginx -t &amp;amp;&amp;amp; sudo systemctl reload nginx&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Without repository access on the server, replace &lt;code&gt;git pull&lt;/code&gt; with an SFTP upload of the changed files, and still build.&lt;/p&gt;

&lt;h2&gt;
  
  
  Environments compared
&lt;/h2&gt;

&lt;p&gt;The setup steps are the same for every environment. What changes is how strict the settings are and what data the server may hold.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Area&lt;/th&gt;
&lt;th&gt;Development (local)&lt;/th&gt;
&lt;th&gt;Staging&lt;/th&gt;
&lt;th&gt;Production&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Purpose&lt;/td&gt;
&lt;td&gt;Building features&lt;/td&gt;
&lt;td&gt;Testing a release on a real server&lt;/td&gt;
&lt;td&gt;Real users and real data&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Env file&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.env.local&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.env.staging&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;.env.production&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Third-party services&lt;/td&gt;
&lt;td&gt;Fake providers&lt;/td&gt;
&lt;td&gt;Fake where the app allows it, real where testing needs it&lt;/td&gt;
&lt;td&gt;Real only&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Login shortcuts (fixed OTP, test logins)&lt;/td&gt;
&lt;td&gt;Allowed&lt;/td&gt;
&lt;td&gt;Only if the app allows it and staging holds no real data&lt;/td&gt;
&lt;td&gt;Never&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Data&lt;/td&gt;
&lt;td&gt;Seed or test data&lt;/td&gt;
&lt;td&gt;Test data only&lt;/td&gt;
&lt;td&gt;Real data&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Secrets&lt;/td&gt;
&lt;td&gt;Local values&lt;/td&gt;
&lt;td&gt;Own values&lt;/td&gt;
&lt;td&gt;Own values, never shared&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTPS&lt;/td&gt;
&lt;td&gt;Not needed&lt;/td&gt;
&lt;td&gt;Required&lt;/td&gt;
&lt;td&gt;Required&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Backups&lt;/td&gt;
&lt;td&gt;None&lt;/td&gt;
&lt;td&gt;Optional&lt;/td&gt;
&lt;td&gt;Daily, tested restores, plus one before every migration&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Monitoring and alerts&lt;/td&gt;
&lt;td&gt;None&lt;/td&gt;
&lt;td&gt;Logs&lt;/td&gt;
&lt;td&gt;Logs, uptime check, disk and certificate expiry alerts&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Production checklist
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;Every provider is real; no fake providers or login shortcuts&lt;/li&gt;
&lt;li&gt;New secrets, created only for production and stored in the password manager&lt;/li&gt;
&lt;li&gt;Env file is &lt;code&gt;chmod 600&lt;/code&gt; and not in git&lt;/li&gt;
&lt;li&gt;Database user has access to its own database only; MySQL is not reachable from the internet&lt;/li&gt;
&lt;li&gt;Automated daily database backup, with a restore tested once&lt;/li&gt;
&lt;li&gt;Firewall allows only 22, 80 and 443; SSH by key only&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;pm2 startup&lt;/code&gt; and &lt;code&gt;pm2 save&lt;/code&gt; done, and the app survives a reboot&lt;/li&gt;
&lt;li&gt;Log rotation on (&lt;code&gt;pm2 install pm2-logrotate&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;sudo certbot renew --dry-run&lt;/code&gt; passes&lt;/li&gt;
&lt;li&gt;An uptime check on the health URL alerts someone when it fails&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  How do I keep a Node.js app running after I close the SSH session?
&lt;/h3&gt;

&lt;p&gt;Run it with PM2 instead of &lt;code&gt;node&lt;/code&gt;: &lt;code&gt;pm2 start ecosystem.config.cjs --env production&lt;/code&gt;. PM2 runs it in the background, restarts it if it crashes, and &lt;code&gt;pm2 startup&lt;/code&gt; plus &lt;code&gt;pm2 save&lt;/code&gt; bring it back after a server reboot (step 7).&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Nginx show 502 Bad Gateway for my Node.js app?
&lt;/h3&gt;

&lt;p&gt;Nginx is running, but it can't reach your app. Either the app isn't running (check &lt;code&gt;pm2 list&lt;/code&gt; and &lt;code&gt;pm2 logs&lt;/code&gt;), or &lt;code&gt;proxy_pass&lt;/code&gt; in the Nginx site points to a different port than the one the app listens on.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need Nginx in front of Node.js?
&lt;/h3&gt;

&lt;p&gt;For production, yes. Nginx handles HTTPS, redirects HTTP to HTTPS, limits upload size and lets several apps share ports 80 and 443 on one server. Your Node.js app stays on a local port that the internet can't reach.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I get a free SSL certificate for a Node.js app?
&lt;/h3&gt;

&lt;p&gt;Use Let's Encrypt with Certbot's Nginx plugin: &lt;code&gt;sudo certbot --nginx -d api.example.com&lt;/code&gt;. The domain's DNS must point to the server first, or certbot fails with &lt;code&gt;NXDOMAIN&lt;/code&gt; (step 10).&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I renew a Let's Encrypt certificate?
&lt;/h3&gt;

&lt;p&gt;You don't need to do it by hand. Certbot installs a scheduled task that renews certificates before they expire. Test it with &lt;code&gt;sudo certbot renew --dry-run&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does PM2 say "Process not found" when I restart my app?
&lt;/h3&gt;

&lt;p&gt;The app is crashing at startup, so PM2 has no running process to restart. Run &lt;code&gt;pm2 logs &amp;lt;app&amp;gt; --err&lt;/code&gt;, fix the error it shows, then &lt;code&gt;pm2 delete &amp;lt;app&amp;gt;&lt;/code&gt; and start it again.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I deploy updates to a Node.js app without breaking it?
&lt;/h3&gt;

&lt;p&gt;Pull, install, build, run migrations, then restart with &lt;code&gt;pm2 restart &amp;lt;app&amp;gt; --update-env&lt;/code&gt;, and check the health URL. Back up the database first when the update changes the schema (see Redeploying an update).&lt;/p&gt;




&lt;p&gt;If this saved you a debugging session, leave a comment with the error that cost you the most time on your own setup, and I'll add it to the troubleshooting tables.&lt;/p&gt;

</description>
      <category>node</category>
      <category>devops</category>
      <category>nginx</category>
      <category>tutorial</category>
    </item>
  </channel>
</rss>
