Strategic Overview

The Modern Web Deployment Triad

The successful deployment of modern web applications hinges on a robust and efficient architecture. This report details a powerful deployment strategy that integrates three core components: Next.js, a leading React framework; Cloudways, a managed cloud hosting platform; and GitHub Actions, a flexible CI/CD engine. This combination provides development velocity, hosting stability, and deployment reliability.

Preparing the Next.js App

The 'Standalone' Output: A Critical Optimization

For self-hosted environments like Cloudways, the single most important optimization is to configure the Next.js build to produce a standalone output. This drastically reduces the size of the deployment artifact.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
};

module.exports = nextConfig;

Final Build Step: Including Static Assets

To ensure all necessary assets are part of the final build artifact, the `build` script in `package.json` should be modified to copy the `public` and `.next/static` directories.

{
  "scripts": {
    "build": "next build && cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/"
  }
}

Provisioning the Cloudways Server

Launch a new server using the "Custom App" option. This provides a clean environment ideal for Node.js. Once active, connect via SSH and install Node.js and the PM2 process manager.

# Install Node.js (e.g., version 18.x)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install the PM2 process manager globally
sudo npm install pm2@latest -g

Architecting Secure Access

Principle of Least Privilege

For CI/CD automation, never use Master credentials. Always create a dedicated, restricted SFTP/SSH user for each application to limit potential security risks.

Storing Credentials in GitHub Secrets

All sensitive credentials must be stored as encrypted secrets in GitHub. They should never be hardcoded into the workflow file.

Constructing the GitHub Actions Workflow

The workflow file, `deploy.yml`, defines the entire CI/CD pipeline. It is triggered on a push to the `main` branch, checks out the code, sets up Node.js, builds the application, and finally deploys it.

name: Deploy Next.js to Cloudways

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies & Build
        run: |
          npm ci
          npm run build

      - name: Deploy to Cloudways
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.CW_SSH_PRIVATE_KEY }}
          REMOTE_HOST: ${{ secrets.CW_HOST }}
          REMOTE_USER: ${{ secrets.CW_USER }}
          REMOTE_PORT: ${{ secrets.CW_PORT }}
          SOURCE: ".next/standalone/"
          TARGET: ${{ secrets.CW_TARGET_PATH }}
          SCRIPT_AFTER: |
            echo "Deployment successful. Running post-deployment script..."
            cd ${{ secrets.CW_TARGET_PATH }}
            npm install --production
            # The following line is corrected to prevent syntax errors.
            # It now correctly uses '||' to fall back to 'pm2 start' if 'pm2 reload' fails.
            pm2 reload my-nextjs-app || pm2 start server.js --name my-nextjs-app
            pm2 save
            echo "Deployment complete."

PM2 Command Cheatsheet

PM2 is a powerful process manager for Node.js. Here are the key commands used in a CI/CD context and for debugging.

Interactive Troubleshooting

Deployment pipelines can sometimes fail. Click on a common error below to see the likely causes and solutions.