AdonisJS Deployment Guide on RamNode VPS

Prerequisites

Requirements

Requirement	Details
RamNode VPS	Minimum 1GB RAM, 1 vCPU recommended
Operating System	Ubuntu 22.04 LTS or Debian 12
Domain Name	Pointed to your VPS IP address
SSH Access	Root or sudo-enabled user
Local Development	AdonisJS project ready for deployment

Initial Server Setup

Connect and Update System

SSH into your server

ssh root@your_server_ip

Update system packages

apt update && apt upgrade -y

Create Deploy User

Running applications as root is a security risk. Create a dedicated deployment user:

Create and configure deploy user

# Create user
adduser deploy

# Add to sudo group
usermod -aG sudo deploy

# Switch to new user
su - deploy

Installing Node.js

Using NodeSource Repository

AdonisJS requires Node.js 20.x or later. Install using the NodeSource repository:

Install Node.js 20.x

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Verify Installation

Check versions

node --version
npm --version

You should see Node.js v20.x.x and npm v10.x.x or later.

Database Configuration

Installing PostgreSQL

Install PostgreSQL

sudo apt install -y postgresql postgresql-contrib

Create Database and User

Access PostgreSQL shell

sudo -u postgres psql

Create database and user

CREATE USER adonisapp WITH PASSWORD 'your_secure_password';
CREATE DATABASE adonisdb OWNER adonisapp;
GRANT ALL PRIVILEGES ON DATABASE adonisdb TO adonisapp;
\q

Replace 'your_secure_password' with a strong, unique password and store it securely.

Deploy Your Application

Create Application Directory

Set up directory structure

sudo mkdir -p /var/www/adonisapp
sudo chown -R deploy:deploy /var/www/adonisapp

Transfer Application

From your local machine

rsync -avz --exclude 'node_modules' --exclude '.env' ./ deploy@your_server_ip:/var/www/adonisapp/

Install Dependencies

Install production dependencies

cd /var/www/adonisapp
npm ci --production

Environment Configuration

Create .env file

NODE_ENV=production
PORT=3333
HOST=127.0.0.1
APP_KEY=your_generated_app_key

DB_CONNECTION=pg
PG_HOST=127.0.0.1
PG_PORT=5432
PG_USER=adonisapp
PG_PASSWORD=your_secure_password
PG_DB_NAME=adonisdb

Generate APP_KEY

node ace generate:key

Run Migrations and Build

Prepare for production

# Run database migrations
node ace migration:run --force

# Build TypeScript for production
node ace build --production

Process Management with PM2

Install PM2

PM2 ensures your application stays running and automatically restarts on crashes:

Install PM2 globally

sudo npm install -g pm2

Create Ecosystem File

ecosystem.config.js

module.exports = {
  apps: [{
    name: 'adonisapp',
    script: './build/server.js',
    instances: 'max',
    exec_mode: 'cluster',
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production'
    }
  }]
};

Start and Configure PM2

Launch and enable startup

# Start application
pm2 start ecosystem.config.js

# Enable startup on boot
pm2 startup
pm2 save

PM2 will display a command to run with sudo - execute it to enable automatic startup.

Nginx Reverse Proxy

Install Nginx

sudo apt install -y nginx

Create Server Block

/etc/nginx/sites-available/adonisapp

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3333;
        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_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400;
    }

    location /public {
        alias /var/www/adonisapp/build/public;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

Enable Site

Activate configuration

sudo ln -s /etc/nginx/sites-available/adonisapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL Certificate with Let's Encrypt

Install Certbot

sudo apt install -y certbot python3-certbot-nginx

Obtain SSL Certificate

Run Certbot

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Verify Auto-Renewal

Test renewal

sudo systemctl status certbot.timer
sudo certbot renew --dry-run

Firewall Configuration

Configure UFW

Set up firewall rules

# Set default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow necessary services
sudo ufw allow ssh
sudo ufw allow 'Nginx Full'

# Enable firewall
sudo ufw enable

Verify Rules

Check firewall status

sudo ufw status verbose

Deployment Automation

Create Deployment Script

~/deploy.sh

#!/bin/bash
set -e

APP_DIR="/var/www/adonisapp"
cd $APP_DIR

echo "Pulling latest changes..."
git pull origin main

echo "Installing dependencies..."
npm ci --production

echo "Running migrations..."
node ace migration:run --force

echo "Building application..."
node ace build --production

echo "Restarting PM2..."
pm2 reload adonisapp

echo "Deployment complete!"

Make script executable

chmod +x ~/deploy.sh

Performance Optimization

Troubleshooting

Issue	Solution
502 Bad Gateway	Check if PM2 is running: `pm2 status`. Verify the application port matches Nginx proxy_pass.
Database Connection Failed	Verify PostgreSQL is running: `sudo systemctl status postgresql`. Check .env credentials.
Permission Denied	Ensure deploy user owns the directory: `sudo chown -R deploy:deploy /var/www/adonisapp`
SSL Certificate Error	Run: `sudo certbot renew`. Check domain DNS points to server IP.
High Memory Usage	Adjust PM2 max_memory_restart in ecosystem.config.js. Consider upgrading VPS.

AdonisJS Deployed Successfully!

Your AdonisJS application is now running in production with PostgreSQL, PM2 process management, Nginx reverse proxy, and SSL encryption. For ongoing maintenance, regularly update system packages, monitor application logs, and keep your Node.js dependencies current.

Deploying AdonisJS