DEV Community: Nathaniel Toju

NestJS Zero-Downtime Deployment on DigitalOcean with GitLab CI/CD and PM2

Nathaniel Toju — Fri, 03 Jul 2026 17:13:00 +0000

Deploying a NestJS backend to production with true zero downtime is more involved than most guides suggest. This is a complete, battle-tested walkthrough — built from real production experience — covering everything from Droplet setup to automated GitLab pipelines that deploy without dropping a single request.

Stack:

Server: DigitalOcean Droplet (Ubuntu 24.04)
Runtime: Node.js v18
Process Manager: PM2 (cluster mode)
Reverse Proxy: Nginx
CI/CD: GitLab CI/CD
Deploy user: deployer (non-root, for security)

Part 1 — Droplet Initial Setup

SSH into your Droplet as root and run the following steps once.

Install Node.js v18

⚠️ Warning
Do NOT use nodesource setup scripts — they may install v20 regardless of the version you specify. Install directly from the official Node.js binary to guarantee the version.

# Remove any existing Node.js installation
apt-get purge -y nodejs npm
apt-get autoremove -y
apt-get autoclean
rm -f /etc/apt/sources.list.d/nodesource.list
rm -f /etc/apt/sources.list.d/node*.list
rm -f /etc/apt/keyrings/nodesource.gpg
rm -f /usr/bin/node /usr/bin/nodejs /usr/bin/npm /usr/bin/npx
apt-get update

# Download and install Node.js v18 directly from nodejs.org
cd /tmp
curl -fsSL https://nodejs.org/dist/v18.20.8/node-v18.20.8-linux-x64.tar.xz -o node18.tar.xz
tar -xJf node18.tar.xz
cp -r node-v18.20.8-linux-x64/bin/* /usr/local/bin/
cp -r node-v18.20.8-linux-x64/lib/* /usr/local/lib/
cp -r node-v18.20.8-linux-x64/include/* /usr/local/include/

# Verify
node -v   # v18.20.8
npm -v

Install PM2 and Nginx

npm install -g pm2
apt-get install -y nginx

Create a non-root deploy user

Never deploy as root. Create a dedicated deployer user:

useradd -m -s /bin/bash deployer

# Create app directory
mkdir -p /var/www/nestapp
chown -R deployer:deployer /var/www/nestapp

# Create PM2 log directory
mkdir -p /var/log/pm2
chown -R deployer:deployer /var/log/pm2

Set up SSH for the deployer user

mkdir -p /home/deployer/.ssh
chmod 700 /home/deployer/.ssh
touch /home/deployer/.ssh/authorized_keys
chmod 600 /home/deployer/.ssh/authorized_keys
chown -R deployer:deployer /home/deployer/.ssh

Configure the firewall

ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw --force enable

Part 2 — Nginx Configuration

Create the Nginx site config

nano /etc/nginx/sites-available/nestapp

Paste the following, replacing your-domain.com with your actual domain or Droplet IP:

upstream nestapp {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;

    location / {
        proxy_pass http://nestapp;
        proxy_http_version 1.1;
        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_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        'upgrade';
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 240s;
        proxy_connect_timeout 10s;
    }

    location /health {
        proxy_pass http://nestapp;
        access_log off;
    }
}

Enable the site

# Symlink to enable
ln -s /etc/nginx/sites-available/nestapp /etc/nginx/sites-enabled/nestapp

# Remove default site
rm /etc/nginx/sites-enabled/default

# Fix file permissions (important — Nginx can't read files owned only by root)
chmod 644 /etc/nginx/sites-available/nestapp

# Test config
nginx -t

# Reload Nginx
systemctl reload nginx

SSL with Certbot

Once your domain DNS is pointing to the Droplet:

apt install certbot python3-certbot-nginx -y
certbot --nginx -d your-domain.com

ℹ️ Note
Make sure dig your-domain.com +short returns your Droplet IP before running certbot, otherwise the ACME challenge will fail.

Part 3 — Project File Setup

ecosystem.config.js

Add this to your project root and commit it to GitLab:

module.exports = {
  apps: [
    {
      name: 'nestapp',
      script: 'dist/main.js',
      instances: 'max',
      exec_mode: 'cluster',
      node_args: '--security-revert=CVE-2023-46809', // remove if not needed
      autorestart: true,
      watch: false,
      max_memory_restart: '512M',
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
      out_file: '/var/log/pm2/nestapp-out.log',
      error_file: '/var/log/pm2/nestapp-error.log',
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      merge_logs: true,
      kill_timeout: 5000,
      listen_timeout: 8000,
      wait_ready: true,
    },
  ],
};

Update src/main.ts

Signal PM2 when each worker is ready — this is what makes zero-downtime reload actually work:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });

  await app.listen(process.env.PORT || 3000);

  // Tell PM2 this worker is ready to receive traffic
  if (process.send) {
    process.send('ready');
  }
}
bootstrap();

Update package.json — disable Husky in production

Without this, npm ci on the server will fail because Husky tries to install git hooks:

"scripts": {
  "prepare": "husky install || true"
}

.gitlab-ci.yml

Add this to your project root:

image: node:18-alpine

stages:
  - install
  - lint
  - test
  - build
  - deploy

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull-push

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_MERGE_REQUEST_IID

variables:
  NODE_ENV: test

install:
  stage: install
  script:
    - npm ci --prefer-offline
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

lint:
  stage: lint
  needs: [install]
  script:
    - npm run lint

test:
  stage: test
  needs: [install]
  script:
    - npm run test -- --passWithNoTests

build:
  stage: build
  needs: [lint, test]
  script:
    - npm run build
    - mkdir -p release
    - cp -r dist package.json package-lock.json ecosystem.config.js release/
  artifacts:
    paths:
      - release/
    expire_in: 1 hour

deploy:
  stage: deploy
  image: alpine:latest
  needs: [build]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  before_script:
    - apk add --no-cache openssh-client rsync bash curl
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
    - ssh-keyscan -H "$DROPLET_HOST" >> ~/.ssh/known_hosts 2>/dev/null
  script:
    # 1. Sync build artifacts — .env and node_modules on the server are preserved
    - |
      rsync -avz --delete \
        --exclude='.env' \
        --exclude='node_modules' \
        release/ \
        $DROPLET_USER@$DROPLET_HOST:/var/www/nestapp/

    # 2. SSH in, install deps, reload with zero downtime
    - |
      ssh $DROPLET_USER@$DROPLET_HOST << ENDSSH
        set -e
        cd /var/www/nestapp

        echo "==> Installing production dependencies..."
        HUSKY=0 npm ci --omit=dev --prefer-offline

        echo "==> Reloading app (zero downtime)..."
        pm2 reload ecosystem.config.js --env production --update-env || \
          pm2 start ecosystem.config.js --env production

        echo "==> Saving PM2 process list..."
        pm2 save

        pm2 list
ENDSSH

    # 3. Health check
    - |
      echo "==> Running health check..."
      sleep 10
      STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://$DROPLET_HOST/ || echo "000")
      if [ "$STATUS" = "200" ] || [ "$STATUS" = "201" ]; then
        echo "Deploy successful! (HTTP $STATUS)"
      else
        echo "Health check failed (HTTP $STATUS) — check pm2 logs"
        exit 1
      fi
  environment:
    name: production
    url: http://$DROPLET_HOST

Part 4 — SSH Key Setup (GitLab ↔ Droplet)

Generate an SSH key pair on your local machine

ssh-keygen -t ed25519 -C "gitlab-deployer" -f ~/.ssh/gitlab_deployer
# Leave passphrase empty — CI/CD can't type a passphrase

This creates two files:

~/.ssh/gitlab_deployer — private key (goes into GitLab)
~/.ssh/gitlab_deployer.pub — public key (goes onto the Droplet)

Add the public key to the Droplet

As root on the Droplet:

> /home/deployer/.ssh/authorized_keys
echo "ssh-ed25519 AAAA...your-public-key... gitlab-deployer" >> /home/deployer/.ssh/authorized_keys

# Permissions are critical — wrong permissions = Permission denied every time
chmod 700 /home/deployer/.ssh
chmod 600 /home/deployer/.ssh/authorized_keys
chown -R deployer:deployer /home/deployer/.ssh

Test it

ssh -i ~/.ssh/gitlab_deployer deployer@your-droplet-ip

Should log in without a password prompt.

Add variables to GitLab

Go to GitLab → Settings → CI/CD → Variables:

Key	Value	Protected	Masked
`SSH_PRIVATE_KEY`	Contents of `~/.ssh/gitlab_deployer`	✅	❌
`DROPLET_HOST`	Your Droplet IP	✅	❌
`DROPLET_USER`	`deployer`	✅	❌
`DROPLET_PATH`	`/var/www/nestapp`	✅	❌

⚠️ Warning
SSH_PRIVATE_KEY cannot be masked — GitLab doesn't support masking multiline values. Set it as Protected instead so it's only available on protected branches.

Part 5 — First-Time Manual Deploy

Before CI/CD can take over, get the app running on the Droplet manually once.

Build and upload from your local machine

npm run build

scp -r dist package.json package-lock.json ecosystem.config.js root@your-droplet-ip:/var/www/nestapp/

ssh root@your-droplet-ip "chown -R deployer:deployer /var/www/nestapp"

Create the .env file on the Droplet

# As deployer
nano /var/www/nestapp/.env

NODE_ENV=production
PORT=3000
# all your other environment variables...

🚨 Important
Never commit .env to GitLab. This file lives only on the Droplet. The rsync command in the pipeline excludes it so it persists safely across every deployment.

Start PM2

cd /var/www/nestapp
HUSKY=0 npm ci --omit=dev
pm2 start ecosystem.config.js --env production
pm2 save

Configure PM2 to survive reboots

# As deployer
pm2 startup
# Copy and run the generated command as root, then:
pm2 save

Part 6 — Trigger the First Automated Pipeline

git add .gitlab-ci.yml ecosystem.config.js package.json
git commit -m "chore: add CI/CD pipeline and PM2 config"
git push origin main

Go to GitLab → CI/CD → Pipelines and watch all 5 stages:

install → lint → test → build → deploy

Every push to main from this point forward triggers a full pipeline and zero-downtime deployment automatically.

Part 7 — How Zero-Downtime Actually Works

PM2 cluster reload works like this:

GitLab CI builds the new dist/ and rsyncs it to the Droplet
pm2 reload sends a graceful signal to worker 0
Worker 0 finishes all in-flight requests then shuts down
A new worker 0 boots, loads the new code, sends the ready signal
PM2 moves to the next worker and repeats
Nginx keeps routing traffic to all other online workers throughout

No requests are dropped. No downtime.

The wait_ready: true and listen_timeout: 8000 in ecosystem.config.js are what make this reliable — PM2 waits for the process.send('ready') signal from main.ts before it considers the new worker healthy.

Part 8 — Useful Commands

# Check running processes
pm2 list

# View live logs
pm2 logs nestapp

# Monitor CPU and memory
pm2 monit

# Zero-downtime reload (always use this for deployments)
pm2 reload nestapp --update-env

# Hard restart (brief downtime — use only if reload fails)
pm2 restart nestapp --update-env

# Reset restart counter
pm2 reset nestapp

# View last 50 log lines
pm2 logs nestapp --lines 50

# Test Nginx config before reloading
nginx -t

# Reload Nginx without downtime
systemctl reload nginx

# Test the app is responding on the Droplet
curl http://localhost:3000

Common Issues and Fixes

Issue	Cause	Fix
`ecosystem.config.js not found`	File not on Droplet yet	Upload manually via `scp` before first CI run
`Permission denied (publickey)`	Wrong SSH folder permissions	`chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys`
`EACCES: permission denied mkdir /node_modules`	SSH heredoc not expanding variables	Use unquoted `ENDSSH` (not `'ENDSSH'`)
`.env deleted on every deploy`	rsync `--delete` removes files not in source	Add `--exclude='.env'` and sync from a single `release/` folder
`husky: not found`	Husky runs `npm ci` prepare script on server	Prefix with `HUSKY=0` → `HUSKY=0 npm ci --omit=dev`
App crash-looping	Missing `.env` variables	Run `pm2 logs nestapp --lines 50` and recreate `.env`
`Cannot find module dist/main.js`	rsync uploaded folder contents not the folder	Use `dist` without trailing slash in rsync
Node version wrong after install	nodesource installs wrong version	Install Node directly from `nodejs.org` binary
PM2 still using old Node version	PM2 daemon started with old binary	`pm2 kill` then `pm2 start ecosystem.config.js --env production`
Nginx `Permission denied` reading config	File permissions too restrictive	`chmod 644 /etc/nginx/sites-available/nestapp`
Certbot ACME challenge fails	DNS not pointed to Droplet yet	Run `dig your-domain.com +short` — must return Droplet IP first

Built from a real production deployment of a NestJS Fintech backend. Every issue in the troubleshooting table was hit and solved during the actual setup. NB: The node version used here is old; however, you are free to use the latest version

Securing Your React Native App with FreeRasp: A Practical Implementation Guide

Nathaniel Toju — Mon, 04 May 2026 09:10:01 +0000

Introduction

Building a mobile application that handles sensitive financial data — crypto transactions, KYC verification, gift cards — means security is not an afterthought. It is a core deliverable.

During the development of a cross-platform fintech application, one of the non-negotiables on the security checklist was runtime application self-protection (RASP). After evaluating our options, we integrated FreeRasp — an open-source mobile security library — into our React Native codebase.

In this article, I'll walk you through what FreeRasp is, why we chose it, how we integrated it into a React Native project, and the key lessons learned along the way.

What is FreeRasp?

FreeRasp is an open-source RASP (Runtime Application Self-Protection) SDK maintained by Talsec. It provides real-time threat detection for mobile applications by monitoring the environment in which your app is running.

It detects threats such as:

Rooted or jailbroken devices — devices where OS security boundaries have been removed
Debugger attachment — active reverse engineering attempts
Emulator detection — app running in an emulated environment (common in fraud scenarios)
Tampering / repackaging — modified APKs or IPAs being distributed
Unofficial stores — app installed from an untrusted source
Hook frameworks — tools like Frida being used to intercept app behaviour
Overlay attacks — malicious apps drawing over your UI to steal input

For a fintech app handling real user funds and identity documents, these are not theoretical threats.

Why FreeRasp Over the Alternatives?

We considered a few options:

Option	Pros	Cons
FreeRasp	Open source, React Native support, active maintenance, no per-user cost	Requires configuration per platform
Appdome	Comprehensive, no-code	Expensive, vendor lock-in
Custom RASP	Full control	Enormous dev effort, hard to maintain

FreeRasp hit the sweet spot for our stage: production-grade security without the enterprise price tag.

Installation

npm install freerasp-react-native
# or
yarn add freerasp-react-native

For iOS, run pod install after:

cd ios && pod install

Basic Configuration

FreeRasp is configured once — typically in your app's entry point or a dedicated security module. Here is the configuration structure we used:

import { useFreeRasp, setThreatListeners } from 'freerasp-react-native';

const config = {
  androidConfig: {
    packageName: 'com.yourapp.package',
    certificateHashes: ['your-certificate-hash'],
    supportedAlternativeStores: [],
  },
  iosConfig: {
    appBundleId: 'com.yourapp.bundle',
    appTeamId: 'YOUR_TEAM_ID',
  },
  watcherMail: 'security@yourcompany.com',
  isProd: true,
};

Important: The certificateHashes field must match the SHA-256 hash of your app's signing certificate. A mismatch will trigger a tamper alert even in your own build.

Handling Threats

This is where the real implementation decision lies. FreeRasp detects threats and calls your handler — but what you do with that information is entirely your responsibility.

const actions = {
  // Critical threats — terminate session or block access
  rootDetected: () => handleCriticalThreat('root'),
  debugDetected: () => handleCriticalThreat('debug'),
  hookDetected: () => handleCriticalThreat('hook'),

  // High severity — warn and limit functionality
  emulatorDetected: () => handleHighThreat('emulator'),
  tamperDetected: () => handleCriticalThreat('tamper'),

  // Medium severity — log and monitor
  unofficialStoreDetected: () => handleMediumThreat('unofficialStore'),
  deviceBindingDetected: () => handleMediumThreat('deviceBinding'),

  // Informational
  passcodeNotSet: () => promptUserToSetPasscode(),
};

const handleCriticalThreat = (threatType) => {
  // Log the event to your backend
  logSecurityEvent(threatType, 'critical');

  // Clear sensitive data from state
  clearSensitiveData();

  // Navigate to a blocked screen
  navigationRef.current?.navigate('SecurityBlock', { reason: threatType });
};

Our Threat Response Strategy

We categorised threats into three tiers and responded accordingly:

Tier 1 — Block immediately (root, hook, tamper, debug in prod)
The user sees a security error screen. No financial actions are possible. The session is terminated and the backend is notified.

Tier 2 — Degrade gracefully (emulator, unofficial store)
Read-only mode is allowed. Transactions and KYC submission are disabled. The user is informed that full functionality requires a verified device.

Tier 3 — Log and monitor (passcode not set, device binding)
The user is prompted with a recommendation. Functionality is not blocked but the event is logged for analytics.

Lessons Learned

1. Test certificate hashes early
We spent time debugging what looked like a tamper detection issue in staging. The root cause was a mismatch between our debug and release certificate hashes. Always configure separate hashes per environment.

2. Don't block users silently
Your UX around security matters. We initially just crashed the blocked screen with no explanation. We updated it to clearly tell users their device environment isn't trusted and guide them to contact support if they believe it's an error.

3. False positives are real
Some older Android devices or development builds can trigger emulator detection unexpectedly. Build a backend feedback mechanism so your security team can review flagged sessions rather than blindly blocking users.

4. Combine with backend validation
FreeRasp is a client-side layer. A determined attacker can bypass it. Pair it with server-side checks: JWT binding, IP monitoring, transaction anomaly detection. Defence in depth is the goal.

5. isProd matters
Always ensure isProd: true in your production builds. FreeRasp behaves differently in dev mode and will not enforce certain checks. We added this as a required CI check before any release.

Conclusion

Integrating FreeRasp into our React Native fintech application significantly raised our security baseline without adding meaningful friction to the user experience. For any app handling financial data, identity documents, or crypto assets, runtime protection is no longer optional.

The library is actively maintained, well-documented, and free — which makes it an easy recommendation for any React Native team working in regulated domains.

If you have questions about the implementation or want to discuss your own RASP strategy, feel free to reach out or leave a comment below.

Nathaniel Toju is a cross-platform mobile and backend engineer based in Lagos, Nigeria, building fintech and healthcare products. He specialises in React Native, NestJS, and secure application architecture.