Production Deployment

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Pre-Deployment Checklist
Docker Production Deployment
Building the Production Image
Deploy with Docker Compose
Production Stack Architecture
Traditional Server Deployment
Server Requirements
Manual Deployment Steps
SSL/TLS Setup with Let’s Encrypt
Platform-as-a-Service Deployments
Deploying to Railway
Deploying to Render
Deploying to Fly.io
Database Management
Migrations
Backup Strategy
Monitoring and Logging
Application Logs
Health Checks
Performance Monitoring
Scaling Considerations
Horizontal Scaling
Vertical Scaling
Troubleshooting
Security Checklist
Next Steps

This guide covers deploying the AdonisJS Starter Kit to production servers using Docker and other deployment strategies.

Pre-Deployment Checklist

Environment Configuration

Ensure all production environment variables are set correctly.

NODE_ENV=production
APP_KEY is set (use node ace generate:key)
Database credentials configured
Email service configured (Resend or SMTP)
OAuth credentials for Google login

Database Setup

Prepare your production database.

# Run migrations
node ace migration:run --force

# Run seeders (if needed)
node ace db:seed

Build Application

Build the production bundle.

# Build application
node ace build

# Test the build
cd build
node bin/server.js

Security Review

Review security settings.

CORS settings configured
Rate limiting enabled
CSRF protection enabled
Secure cookies enabled (HTTPS)
Database connections use SSL

Docker Production Deployment

Building the Production Image

The production Dockerfile is optimized for size and security:

FROM node:22-alpine

# Install compatibility libraries
RUN apk add --no-cache libc6-compat

WORKDIR /app

# Enable pnpm
RUN npm install -g corepack@latest
RUN corepack enable pnpm

COPY . .

# Install dependencies
ENV CI=true
RUN pnpm install --force --frozen-lockfile

# Build application
WORKDIR /app/apps/web
RUN node ace build --ignore-ts-errors

WORKDIR /app/apps/web/build

EXPOSE 3333

CMD ["node", "bin/server.js"]

Key Features:

Alpine Linux base (minimal size)
Multi-stage build considerations
Frozen lockfile for reproducibility
Production build optimization

Deploy with Docker Compose

# Build and start all services
docker compose -f docker-compose.prod.yaml up -d --build

# Check service status
docker compose -f docker-compose.prod.yaml ps

# View logs
docker compose -f docker-compose.prod.yaml logs -f web

Production Stack Architecture

The production setup includes:

Nginx Reverse Proxy

Handles incoming HTTP/HTTPS traffic on ports 80/443.

server {
  listen 80;
  server_name example.com;
  client_max_body_size 100M;
  
  location / {
    proxy_pass http://web:3333;
    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;
  }
}

AdonisJS Application

The web service runs the Node.js application on port 3333.

web:
  restart: always
  environment:
    HOST: web
    NODE_ENV: production
    DB_HOST: pgsql

PostgreSQL Database

Internal database with no exposed ports.

pgsql:
  restart: always
  ports: []  # No external access

Traditional Server Deployment

Server Requirements

Minimum Specs

1 CPU core
1GB RAM
10GB storage
Ubuntu 22.04 or later

Recommended Specs

2+ CPU cores
2GB+ RAM
20GB+ storage
Load balancer ready

Manual Deployment Steps

Install Dependencies

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install pnpm
corepack enable pnpm

# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib

Setup Application

# Clone repository
git clone <your-repo-url> /var/www/app
cd /var/www/app

# Install dependencies
pnpm install --prod

# Build application
cd apps/web
node ace build

Configure Environment

# Copy environment file
cp apps/web/.env.example apps/web/.env

# Edit with production values
nano apps/web/.env

Never commit .env files to version control. Use secret management tools.

Setup Process Manager

Use PM2 to manage the Node.js process:

# Install PM2
npm install -g pm2

# Start application
cd /var/www/app/apps/web/build
pm2 start bin/server.js --name "adonisjs-app"

# Save PM2 configuration
pm2 save

# Setup startup script
pm2 startup

Configure Nginx

server {
  listen 80;
  server_name example.com;
  
  location / {
    proxy_pass http://localhost: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-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_cache_bypass $http_upgrade;
  }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

SSL/TLS Setup with Let’s Encrypt

# Install Certbot
sudo apt install -y certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d example.com -d www.example.com

# Auto-renewal is configured automatically
sudo certbot renew --dry-run

Platform-as-a-Service Deployments

Deploying to Railway

Connect Repository

Create a new project on Railway
Connect your GitHub repository
Select the apps/web directory as root

Configure Services

Add services:

PostgreSQL database (from Railway marketplace)
Redis (optional, for caching)

Set Environment Variables

Configure in Railway dashboard:

NODE_ENV=production
APP_KEY=${{ railway.secret }}
DB_HOST=${{ Postgres.PGHOST }}
DB_PORT=${{ Postgres.PGPORT }}
DB_USER=${{ Postgres.PGUSER }}
DB_PASSWORD=${{ Postgres.PGPASSWORD }}
DB_DATABASE=${{ Postgres.PGDATABASE }}

Deploy

Railway automatically deploys on git push.

git push origin main

Deploying to Render

Create Web Service

Go to Render Dashboard
New → Web Service
Connect repository

Configure Build

# Build Command
cd apps/web && pnpm install && node ace build

# Start Command
cd apps/web/build && node bin/server.js

# Root Directory
./

Add PostgreSQL

Create PostgreSQL database from Render dashboard
Copy connection details
Add to environment variables

Deploy

Render auto-deploys on push to main branch.

Deploying to Fly.io

Install Fly CLI

curl -L https://fly.io/install.sh | sh
fly auth login

Initialize App

cd apps/web
fly launch

Create Database

fly postgres create
fly postgres attach <db-name>

Deploy

fly deploy

Database Management

Migrations

# Production migrations
node ace migration:run --force

# Check status
node ace migration:status

# Rollback (careful!)
node ace migration:rollback --force

Backup Strategy

Manual Backup
Docker Backup
Automated Backup

# Backup database
pg_dump -h localhost -U root -d app > backup-$(date +%Y%m%d).sql

# Restore database
psql -h localhost -U root -d app < backup-20260303.sql

# Backup from container
docker compose exec pgsql pg_dump -U root app > backup.sql

# Restore to container
cat backup.sql | docker compose exec -T pgsql psql -U root app

# Create backup script
cat > /usr/local/bin/db-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d-%H%M%S)
pg_dump -U root app | gzip > "$BACKUP_DIR/backup-$DATE.sql.gz"
# Keep only last 7 days
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
EOF

# Make executable
chmod +x /usr/local/bin/db-backup.sh

# Add to crontab (daily at 2 AM)
echo "0 2 * * * /usr/local/bin/db-backup.sh" | crontab -

Monitoring and Logging

Application Logs

# Follow logs
docker compose logs -f web

# Last 100 lines
docker compose logs --tail=100 web

# Export logs
docker compose logs web > app.log

Health Checks

Implement health check endpoint:

// routes/health.ts
import router from '@adonisjs/core/services/router'

router.get('/health', async ({ response }) => {
  return response.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
  })
})

Configure in Docker:

web:
  healthcheck:
    test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3333/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s

Performance Monitoring

Consider integrating:

Application Monitoring

New Relic
Datadog
Sentry for error tracking

Infrastructure Monitoring

Scaling Considerations

Horizontal Scaling

Stateless Application

Ensure your application is stateless:

Use database for sessions (not memory)
Store uploads in S3/cloud storage
Use Redis for cache and queues

Load Balancer

Configure load balancer (Nginx, HAProxy, or cloud LB):

upstream backend {
  least_conn;
  server web1:3333;
  server web2:3333;
  server web3:3333;
}

Database Connection Pooling

Configure in config/database.ts:

postgres: {
  pool: {
    min: 2,
    max: 10,
  },
}

Vertical Scaling

Adjust resource limits:

web:
  deploy:
    resources:
      limits:
        cpus: '2.0'
        memory: 2G
      reservations:
        cpus: '1.0'
        memory: 1G

Troubleshooting

Application won't start

Check environment variables:

docker compose exec web env | grep NODE_ENV

Verify build completed:
```
ls -la apps/web/build
```
Check for missing dependencies:
```
docker compose exec web pnpm install
```

Database connection errors

Verify database is running:
```
docker compose ps pgsql
```

Test connection:

docker compose exec web node ace db:check

Check credentials in .env

High memory usage

Check Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=2048"

Review database query performance
Implement caching strategy

Slow response times

Enable query logging:
```
postgres: {
  debug: true,
}
```
Add database indexes
Implement Redis caching
Use CDN for static assets

Security Checklist

Next Steps

Docker Setup

Learn about Docker configuration

Environment Variables

Configure environment variables

Docker Setup Environment Configuration

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Getting Started

Project Structure

Core Features

Development

Deployment

Pre-Deployment Checklist

Docker Production Deployment

Building the Production Image

Deploy with Docker Compose

Production Stack Architecture

Traditional Server Deployment

Server Requirements

Minimum Specs

Recommended Specs

Manual Deployment Steps

SSL/TLS Setup with Let’s Encrypt

Platform-as-a-Service Deployments

Deploying to Railway

Deploying to Render

Deploying to Fly.io

Database Management

Migrations

Backup Strategy

Monitoring and Logging

Application Logs

Health Checks

Performance Monitoring

Application Monitoring

Infrastructure Monitoring

Scaling Considerations

Horizontal Scaling

Vertical Scaling

Troubleshooting

Security Checklist

Next Steps

Docker Setup

Environment Variables

Build docs developers (and LLMs) love

Getting Started

Project Structure

Core Features

Development

Deployment

​Pre-Deployment Checklist

​Docker Production Deployment

​Building the Production Image

​Deploy with Docker Compose

​Production Stack Architecture

​Traditional Server Deployment

​Server Requirements

Minimum Specs

Recommended Specs

​Manual Deployment Steps

​SSL/TLS Setup with Let’s Encrypt

​Platform-as-a-Service Deployments

​Deploying to Railway

​Deploying to Render

​Deploying to Fly.io

​Database Management

​Migrations

​Backup Strategy

​Monitoring and Logging

​Application Logs

​Health Checks

​Performance Monitoring

Application Monitoring

Infrastructure Monitoring

​Scaling Considerations

​Horizontal Scaling

​Vertical Scaling

​Troubleshooting

​Security Checklist

​Next Steps

Docker Setup

Environment Variables

Build docs developers (and LLMs) love

Pre-Deployment Checklist

Docker Production Deployment

Building the Production Image

Deploy with Docker Compose

Production Stack Architecture

Traditional Server Deployment

Server Requirements

Manual Deployment Steps

SSL/TLS Setup with Let’s Encrypt

Platform-as-a-Service Deployments

Deploying to Railway

Deploying to Render

Deploying to Fly.io

Database Management

Migrations

Backup Strategy

Monitoring and Logging

Application Logs

Health Checks

Performance Monitoring

Scaling Considerations

Horizontal Scaling

Vertical Scaling

Troubleshooting

Security Checklist

Next Steps