Documentation for Deploying "HNG Boilerplate", A Next.js Application using GitHub Actions

Introduction

This guide provides a step-by-step explanation of deploying the "HNG Boilerplate" Next.js application using a CI/CD pipeline powered by GitHub Actions. The deployment process includes building the application, uploading artifacts, and deploying them on a server with Nginx configured to route traffic to the application.

Prerequisites

Before starting, ensure you have the following:

• A GitHub repository with your "HNG Boilerplate" Next.js application.

• A server (e.g., Ubuntu) with SSH access.
  Nginx installed on your server.

• A domain name pointing to your server's IP address.

Dependencies

• Node.js & pnpm: Required for building the "HNG Boilerplate."

• Nginx: Used as a reverse proxy to direct traffic from your domain to the "HNG Boilerplate."

• PM2: Manages and keeps your Node.js application running.

GitHub Actions Workflows

Build and Upload Workflow

This workflow is responsible for building the "HNG Boilerplate" application and uploading the production artifacts.

name: Build and Upload

on:
  push:
    branches:
      - dev

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.event.repository.fork == false

    steps:
    - uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: "20"

    - name: Cache pnpm modules
      uses: actions/cache@v3
      with:
        path: ~/.pnpm-store
        key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
        restore-keys: |
          ${{ runner.os }}-pnpm-

    - name: Install pnpm
      uses: pnpm/action-setup@v4
      with:
        version: 9

    - name: Install dependencies
      run: pnpm install

    - name: Build Next.js application
      run: pnpm build

    - name: Archive production artifacts
      run: tar -czf boilerplate.tar.gz .next public

    - name: Upload production artifacts
      uses: actions/upload-artifact@v3
      with:
        name: boilerplate-build
        path: boilerplate.tar.gz

    - name: Delete zip file
      run: rm -f boilerplate.tar.gz

• Node.js Setup: Ensures the correct Node.js version is used.

• Caching: Speeds up workflow by caching pnpm modules.

• Build Process: Builds the "HNG Boilerplate" and archives the production files.

• Artifact Upload: Uploads the build as an artifact for the deployment process.

Deployment Workflow

This workflow is triggered upon the successful completion of the "Build and Upload" workflow and handles the deployment of the "HNG Boilerplate."

name: Pheonix Deployment

on:
  workflow_run:
    workflows: ["Build and Upload"]
    types:
      - completed

jobs:   
  deploy:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest

    environment:
      name: "panther-expressjs"
      url: ${{ vars.URL }}

    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          run-id: ${{ github.event.workflow_run.id }}
          name: boilerplate-build
          path: .

      - name: Decode ENV secret
        run: |
         echo "${{ secrets.ENV }}" > encoded_env.txt
         base64 -d encoded_env.txt > .env.expressjs

      - name: Copy Artifacts to server
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          password: ${{ secrets.PASSWORD }}
          source: ".env.expressjs,boilerplate.tar.gz"
          target: "/tmp/expressjs"

      - name: Deploy on server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          password: ${{ secrets.PASSWORD }}
          script: |
             sudo npm install -g pm2
            mkdir -p hng_boilerplate_nextjs
            cd hng_boilerplate_nextjs
            tar -xzf /tmp/expressjs/boilerplate.tar.gz
            mv /tmp/expressjs/.env.expressjs .env
            rm -f /tmp/expressjs/boilerplate.tar.gz
            cp -r .next/standalone/* .
            pm2 restart nextjs_boilerplate --update-env

• Artifact Download: Retrieves the build artifacts from the "Build and Upload" workflow.

• Environment Setup: Decodes and applies environment variables for the deployment.

• Server Deployment: Transfers the necessary files to the server and restarts the application using PM2.

Nginx Configuration

To route your domain to the "HNG Boilerplate" application running on the
server, configure Nginx as follows:

• Install Nginx on your server:

sudo apt update
sudo apt install nginx

• Configure Nginx by editing the default site configuration or creating a new one

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

    location / {
        proxy_pass http://localhost:port;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    error_page 404 /404.html;
    location = /404.html {
        internal;
    }
}

• Enable the configuration and restart Nginx

sudo ln -s /etc/nginx/path to 'URL' /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

• Set up SSL with Certbot: Use Certbot to automatically obtain and install an SSL certificate for your domain:

sudo certbot --nginx -d 'URL'

Conclusion

This guide provides a comprehensive overview of deploying the "HNG Boilerplate" using GitHub Actions and Nginx. The combination of automated CI/CD pipelines and a robust web server setup ensures a smooth and efficient deployment process.