Next.js Deployment with GitLab CI/CD: From Server Setup to Automation

GitLab CI → git pull → npm ci → npm run build → PM2 reload → done

# System update
sudo apt update && sudo apt upgrade -y
 
# Install basic packages
sudo apt install -y git curl ufw fail2ban build-essential
 
# Firewall setup
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

# 1. Create SSH key on local machine (if you don't have one yet)
# Run on LOCAL machine, not on server!
ssh-keygen -t ed25519 -C "your_email@example.com"
 
# 2. Copy public key to server
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@your_server_ip
 
# 3. Verify you can login with key
ssh user@your_server_ip
 
# 4. Disable password login (SSH keys only)
sudo nano /etc/ssh/sshd_config
 
# Find and change these lines:
# PasswordAuthentication no
# PubkeyAuthentication yes
# PermitRootLogin no
# ChallengeResponseAuthentication no
 
# 5. Restart SSH
sudo systemctl restart sshd
 
# 6. DON'T CLOSE current session! Open new terminal window
# and verify you can login with key

# Installation (already installed above)
sudo apt install -y fail2ban
 
# Create local configuration
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
 
# Configure basic SSH protection
sudo tee /etc/fail2ban/jail.local << 'EOF'
[DEFAULT]
bantime = 1h
findtime = 10m
maxretry = 5
destemail = your_email@example.com
sendername = Fail2Ban
 
[sshd]
enabled = true
port = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s
EOF
 
# Start Fail2Ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
 
# Check status
sudo fail2ban-client status
sudo fail2ban-client status sshd

# Reset rules (if you need to start from scratch)
sudo ufw --force reset
 
# Default policy: deny all incoming, allow outgoing
sudo ufw default deny incoming
sudo ufw default allow outgoing
 
# Allow SSH (IMPORTANT: do this before enable!)
sudo ufw allow 22/tcp comment 'SSH'
 
# Allow HTTP/HTTPS for NPM or Nginx
sudo ufw allow 80/tcp comment 'HTTP'
sudo ufw allow 443/tcp comment 'HTTPS'
 
# If using NPM, allow admin panel (only for your IP!)
# sudo ufw allow from YOUR_IP to any port 81 comment 'NPM Admin'
 
# Rate limit SSH connections (DDoS protection)
sudo ufw limit 22/tcp
 
# Enable firewall
sudo ufw enable
 
# Check rules
sudo ufw status numbered

# Install Node.js 20 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
 
# Check versions
node -v  # should be >= v20.x
npm -v   # should be >= 10.x
 
# Configure npm for production
npm config set loglevel error

# Install PM2 globally
sudo npm install -g pm2
 
# Configure PM2 autostart on reboot
pm2 startup systemd -u $USER --hp $HOME
# Command will output a string with sudo: execute it
 
# Check systemd service
sudo systemctl status pm2-$USER

# Create directory for NPM
mkdir -p ~/nginx-proxy-manager
cd ~/nginx-proxy-manager
 
# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'     # HTTP
      - '443:443'   # HTTPS
      - '81:81'     # Admin UI
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    environment:
      DB_SQLITE_FILE: "/data/database.sqlite"
EOF
 
# Start NPM
docker-compose up -d
 
# Check status
docker-compose ps

# Custom settings for Next.js
location /_next/static/ {
    proxy_cache_valid 200 60m;
    add_header Cache-Control "public, immutable";
}
 
location /api/health {
    access_log off;
}
 
# Timeouts for SSR
proxy_read_timeout 60s;
proxy_connect_timeout 60s;

# /etc/nginx/sites-available/potapov.me
server {
    listen 80;
    server_name potapov.me www.potapov.me;
 
    location / {
        proxy_pass http://localhost: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_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 60s;
    }
}

sudo certbot --nginx -d potapov.me -d www.potapov.me

# Create application directory
sudo mkdir -p /var/www/potapov.me
sudo chown -R $USER:$USER /var/www/potapov.me
 
# Create directories for logs and backups
mkdir -p /var/www/potapov.me/{logs,backups}
 
# Create .env file (will fill via GitLab CI later)
touch /var/www/potapov.me/.env

// ecosystem.config.cjs
module.exports = {
  apps: [
    {
      name: "potapov-me",
      cwd: "/var/www/potapov.me",
      script: "node_modules/next/dist/bin/next",
      args: "start -p 3000",
 
      // Environment variables
      env: {
        NODE_ENV: "production",
        PORT: 3000,
      },
 
      // Cluster mode for zero-downtime reload
      exec_mode: "cluster",
      instances: 2, // or 'max' to use all CPU cores
 
      // Auto-restart settings
      autorestart: true,
      max_restarts: 10,
      min_uptime: "10s",
      max_memory_restart: "500M", // Restart on memory limit
 
      // Logging
      out_file: "./logs/pm2-out.log",
      error_file: "./logs/pm2-error.log",
      log_date_format: "YYYY-MM-DD HH:mm:ss Z",
      merge_logs: true,
 
      // Graceful shutdown
      kill_timeout: 5000,
      wait_ready: true,
      listen_timeout: 10000,
    },
  ],
};

// app/api/health/route.ts
import { NextResponse } from "next/server";
 
export async function GET() {
  const health = {
    status: "ok",
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    environment: process.env.NODE_ENV,
  };
 
  return NextResponse.json(health, { status: 200 });
}

# On server: create deploy user (optional)
sudo adduser deployer
sudo usermod -aG sudo deployer
 
# Add to sudoers for commands without password (if needed)
# For NPM usually not required as it works via Docker
# For plain Nginx:
# echo "deployer ALL=(ALL) NOPASSWD: /usr/bin/systemctl reload nginx, /usr/bin/pm2" | sudo tee /etc/sudoers.d/deployer
 
# Switch to deployer
su - deployer
 
# Create SSH keys (on local machine or in GitLab CI/CD Settings)
ssh-keygen -t ed25519 -C "gitlab-ci@potapov.me" -f ~/.ssh/gitlab_ci_ed25519
 
# Copy public key to server
# On server (under deployer):
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
# Paste contents of gitlab_ci_ed25519.pub
chmod 600 ~/.ssh/authorized_keys

# .gitlab-ci.yml
# GitLab CI/CD pipeline for Next.js deployment
 
# Global settings
image: node:20-alpine
 
# Pipeline stages
stages:
  - install
  - lint
  - test
  - build
  - deploy
  - healthcheck
  - rollback
 
# Cache node_modules for speedup
cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
    - .npm/
 
# Environment variables
variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"
  NEXT_TELEMETRY_DISABLED: "1"
 
# Template for Node.js jobs
.node_job:
  before_script:
    - node -v
    - npm -v
 
# === STAGE: Install Dependencies ===
install_dependencies:
  extends: .node_job
  stage: install
  script:
    - echo "Installing dependencies..."
    - npm ci --prefer-offline --no-audit
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour
  only:
    - main
    - develop
    - merge_requests
 
# === STAGE: Lint ===
lint:
  extends: .node_job
  stage: lint
  dependencies:
    - install_dependencies
  script:
    - echo "Running ESLint..."
    - npm run lint
  only:
    - main
    - develop
    - merge_requests
 
# === STAGE: Build ===
build:
  extends: .node_job
  stage: build
  dependencies:
    - install_dependencies
  script:
    - echo "Building Next.js application..."
    - npm run build
  artifacts:
    paths:
      - .next/
      - public/
    expire_in: 1 hour
  only:
    - main
    - develop
 
# === STAGE: Deploy to Production ===
deploy_production:
  stage: deploy
  image: alpine:latest
  dependencies:
    - build
  before_script:
    # Install SSH client
    - apk add --no-cache openssh-client bash git
 
    # Setup SSH
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
 
  script:
    - echo "Deploying to production server..."
 
    # Create backup of current version
    - |
      ssh $SSH_USER@$SSH_HOST "
        cd $DEPLOY_PATH &&
        if [ -d .next ]; then
          echo 'Creating backup...' &&
          BACKUP_NAME=backup-\$(date +%Y%m%d-%H%M%S) &&
          mkdir -p backups &&
          tar -czf backups/\$BACKUP_NAME.tar.gz .next package.json package-lock.json &&
          echo 'Backup created: '\$BACKUP_NAME &&
 
          # Keep only last 5 backups
          cd backups &&
          ls -t | tail -n +6 | xargs -r rm &&
          cd ..
        fi
      "
 
    # Deploy via git pull on server
    - echo "Deploying via git pull..."
    - |
      ssh $SSH_USER@$SSH_HOST "
        cd $DEPLOY_PATH &&
        git fetch origin &&
        git reset --hard origin/main &&
        echo 'Code updated from git'
      "
 
    # Install dependencies, build and reload PM2
    - |
      ssh $SSH_USER@$SSH_HOST "
        cd $DEPLOY_PATH &&
        echo 'Installing dependencies...' &&
        npm ci --prefer-offline &&
 
        echo 'Building application...' &&
        npm run build &&
 
        echo 'Reloading PM2...' &&
        pm2 reload ecosystem.config.cjs --update-env &&
 
        echo 'Waiting for app to start...' &&
        sleep 5 &&
 
        pm2 status
      "
 
    - echo "Deployment completed successfully!"
 
  environment:
    name: production
    url: https://potapov.me
 
  only:
    - main
 
# === STAGE: Health Check ===
healthcheck_production:
  stage: healthcheck
  image: alpine:latest
  needs: ["deploy_production"]
  before_script:
    - apk add --no-cache curl
 
  script:
    - echo "Checking application health..."
    - |
      for i in {1..10}; do
        if curl -f -s https://potapov.me/api/health > /dev/null; then
          echo "✅ Health check passed!"
          exit 0
        else
          echo "⏳ Waiting for app to be ready (attempt $i/10)..."
          sleep 5
        fi
      done
      echo "❌ Health check failed after 10 attempts"
      exit 1
 
  dependencies:
    - deploy_production
 
  only:
    - main
 
# === STAGE: Rollback (manual) ===
rollback_production:
  stage: rollback
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts
 
  script:
    - echo "Rolling back to previous version..."
    - |
      ssh $SSH_USER@$SSH_HOST "
        cd $DEPLOY_PATH &&
 
        # Find latest backup
        LATEST_BACKUP=\$(ls -t backups/*.tar.gz | head -1) &&
 
        if [ -z \"\$LATEST_BACKUP\" ]; then
          echo '❌ No backups found!'
          exit 1
        fi &&
 
        echo 'Restoring from backup: '\$LATEST_BACKUP &&
 
        # Restore from backup
        tar -xzf \$LATEST_BACKUP &&
 
        # Reload PM2
        pm2 reload ecosystem.config.cjs &&
 
        echo '✅ Rollback completed!'
      "
 
  when: manual
  only:
    - main

potapov.me {
    reverse_proxy localhost:3000
}

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# Check PM2 systemd service status
systemctl status pm2-$USER
 
# If service not active, configure autostart
pm2 startup systemd -u $USER --hp $HOME
# Execute the sudo command that PM2 outputs
 
# Save current process list
pm2 save
 
# Test
sudo reboot
# After reboot check
pm2 status

# 1. Check that SSH key is added to GitLab Variables
# Settings → CI/CD → Variables → SSH_PRIVATE_KEY
 
# 2. Make sure public key is added on server
cat ~/.ssh/authorized_keys
 
# 3. Check .ssh directory permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
 
# 4. Check SSH connection manually
ssh -i ~/.ssh/gitlab_ci_key user@server
 
# 5. Add -vvv for diagnostics
ssh -vvv user@server

# 1. Check that application is running
pm2 status
pm2 logs app-name --lines 50
 
# 2. Check if process is listening on the right port
sudo netstat -tlnp | grep 3000
# or
sudo lsof -i :3000
 
# 3. Check health endpoint locally
curl http://localhost:3000/api/health
 
# 4. Check from external IP
curl http://YOUR_IP:3000/api/health
 
# 5. Check Nginx/NPM logs
docker logs nginx-proxy-manager_app_1

# 1. Check available memory
free -h
 
# 2. Create swap file (if none)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
 
# 3. Make swap permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
 
# 4. Or increase heap for Node.js in package.json
"scripts": {
  "build": "NODE_OPTIONS='--max-old-space-size=2048' next build"
}

# Option 1: Hard reset (removes all local changes)
ssh user@server "
  cd /var/www/app &&
  git fetch origin &&
  git reset --hard origin/main &&
  git clean -fd
"
 
# Option 2: Stash local changes
ssh user@server "
  cd /var/www/app &&
  git stash &&
  git pull origin main
"
 
# Option 3: If repository is large, use shallow clone
# During initial setup:
git clone --depth 1 https://gitlab.com/user/repo.git /var/www/app
 
# During deployment:
ssh user@server "
  cd /var/www/app &&
  git fetch --depth 1 &&
  git reset --hard origin/main
"

# === PM2 ===
pm2 status                      # All processes status
pm2 logs app-name --lines 100   # Application logs
pm2 monit                       # Real-time monitoring
pm2 describe app-name           # Detailed information
pm2 reset app-name              # Reset restart counters
 
# === Port checking ===
sudo netstat -tlnp              # All listening ports
sudo lsof -i :3000              # Process on port 3000
nc -zv localhost 3000           # Check port availability
 
# === System logs ===
journalctl -u pm2-$USER -f      # PM2 systemd service logs
journalctl -u nginx -f          # Nginx logs (if not Docker)
tail -f /var/log/syslog         # System logs
 
# === Docker (for NPM) ===
docker ps                       # Running containers
docker logs <container> -f      # Container logs
docker exec -it <container> sh  # Enter container
 
# === Disk space ===
df -h                           # Free disk space
du -sh /var/www/*               # Directory sizes
du -sh node_modules .next       # Artifact sizes
 
# === Memory ===
free -h                         # Memory and swap
htop                            # Interactive monitoring