How to Migrate a Node.js Application to a New Server

How to Migrate a Node.js Application to a New Server

Migrating a Node.js application to a new Breeze instance involves transferring your code, reinstalling dependencies, moving any databases, and configuring the process manager and reverse proxy. This guide covers the full process step by step.

Prerequisites

• SSH access to both the source server and your new Breeze
• Node.js and npm installed on the new Breeze (use nvm for version management)
• A reverse proxy such as Nginx configured on the Breeze
• Any databases your app depends on already migrated or accessible

Step 1: Install Node.js on Your Breeze

Use Node Version Manager (nvm) to install the exact Node.js version your application requires:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
node -v

Step 2: Transfer Application Code

Copy your application from the source server, excluding node_modules since you will reinstall dependencies on the Breeze:

rsync -avz --exclude='node_modules' --exclude='.env' \
  user@source-ip:/home/app/myapp/ /home/app/myapp/

Transfer your .env file separately and update any environment-specific values like database hosts, API keys, and port numbers for the new Breeze.

Step 3: Install Dependencies

On the Breeze, navigate to your application directory and install dependencies:

cd /home/app/myapp
npm ci --production

Using npm ci instead of npm install ensures a clean install from the lockfile, producing a deterministic node_modules directory.

Step 4: Set Up PM2 Process Manager

Install PM2 globally and configure it to manage your application:

npm install -g pm2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

If you do not have an ecosystem file, create one:

module.exports = {
  apps: [{
    name: 'myapp',
    script: 'server.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};

Step 5: Configure Nginx Reverse Proxy

Create an Nginx server block to proxy requests to your Node.js app:

server {
    listen 80;
    server_name myapp.example.com;

    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_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }
}

Step 6: Test and Finalize

Test the application thoroughly on the Breeze before pointing DNS. Check all API endpoints, WebSocket connections if applicable, and any background jobs. Monitor logs with pm2 logs to catch any runtime errors. Once confirmed working, update DNS and your migration is complete.