DEV Community

Cover image for Automate Next.js Deployment to AWS EC2 with Ansible — A Beginner-Friendly Guide
cuongnp
cuongnp

Posted on

Automate Next.js Deployment to AWS EC2 with Ansible — A Beginner-Friendly Guide

#nextjs #javascript #ansible #aws

The Problem: Manual Deployment Hell

Picture this: You've built an amazing Next.js app. Your users love it. But every time you want to deploy a new feature, you have to:

  1. SSH into your server
  2. Pull the latest code
  3. Run npm install and npm run build
  4. Restart your app
  5. Pray nothing breaks

In my company, our maintainer had to update apps one by one across multiple servers. It was slow, error-prone, and frankly... boring.

I thought to myself: "Can I automate this process?"

The answer? Yes! And that's where Ansible comes in.

What is Ansible? (Explained for JavaScript Developers)

Think of Ansible like package.json scripts, but for servers instead of your local machine.

Instead of running:

npm run build
npm start
Enter fullscreen mode Exit fullscreen mode

You write an Ansible "playbook" that does this across multiple servers automatically:

- name: Build and deploy Next.js app
  hosts: all
  tasks:
    - name: Install dependencies
      npm: path=/home/app
    - name: Build app
      command: npm run build
    - name: Start with PM2
      command: pm2 start ecosystem.config.js
Enter fullscreen mode Exit fullscreen mode

The magic? One command deploys to 1 server or 100 servers. Same process, zero headaches.

Our Deployment Architecture

Here's what we're building:

Deployment Architecture

Why this setup?

  • GitHub Actions: Free CI/CD (if you're already using GitHub)
  • Ansible Controller: One place to manage all deployments
  • Multiple App Servers: Scale easily by adding more EC2 instances

Step 1: Create Your Ansible Controller (EC2)

First, let's set up our "command center" — an EC2 instance that will run Ansible.

Launch EC2 Instance

  1. AMI: Amazon Linux 2 (free tier eligible)
  2. Instance Type: t2.micro (free tier)
  3. Security Group: Allow SSH (port 22) from your IP
  4. Key Pair: Create or use existing (you'll need this!)

Install Ansible

SSH into your controller and run:

sudo yum update -y
sudo yum install -y python3-pip
pip3 install ansible --user

# Add to PATH
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Verify installation
ansible --version
Enter fullscreen mode Exit fullscreen mode

💡 Pro Tip: Save your SSH key (.pem file) securely — you'll need it for GitHub Actions later!

Step 2: Create Your App Server(s)

Now let's create the EC2 instance(s) where your Next.js app will run.

Launch App Server EC2

  1. AMI: Amazon Linux 2023 (newer, better performance)
  2. Instance Type: t3.micro or larger (depending on your app)
  3. Security Group:
    • SSH (port 22) from Ansible Controller
    • HTTP (port 3000) from anywhere (or your Load Balancer)
  4. Key Pair: Same as your Ansible Controller

Test SSH Connection

From your Ansible Controller, test that you can reach your app server:

ssh -i ~/.ssh/your-key.pem ec2-user@YOUR-APP-SERVER-IP
Enter fullscreen mode Exit fullscreen mode

If this works, you're ready for the next step!

Step 3: Create the Ansible Playbook

This is where the magic happens. Create a file called deploy.yml:

- name: Deploy Next.js app to EC2
  hosts: nextjs_servers
  gather_facts: yes
  become: yes
  vars:
    app_dir: /home/ec2-user/app
    app_owner: ec2-user
    app_group: ec2-user
    app_repo: https://github.com/YOUR-USERNAME/YOUR-REPO.git
    app_branch: main
    app_subdir: my-nextjs-app
  tasks:
    - name: Check if Node.js is installed
      ansible.builtin.command: node -v
      register: node_check
      ignore_errors: true
      changed_when: false

    - name: Ensure prerequisites are installed on Amazon/RedHat (dnf)
      when: (ansible_facts.os_family | lower) in ["redhat"] or (ansible_facts.distribution == 'Amazon')
      ansible.builtin.dnf:
        name:
          - git
          - ca-certificates
        state: present

    - name: Ensure application directory exists
      ansible.builtin.file:
        path: "{{ app_dir }}"
        state: directory
        owner: "{{ app_owner }}"
        group: "{{ app_group }}"
        mode: "0755"

    - name: Checkout application repository
      ansible.builtin.git:
        repo: "{{ app_repo }}"
        dest: "{{ app_dir }}"
        version: "{{ app_branch }}"
        force: yes
        update: yes
      become_user: "{{ app_owner }}"

    - name: Install Node.js 18.x on Amazon Linux 2023
      when: ansible_facts.distribution == 'Amazon' and ansible_facts.distribution_major_version == '2023' and (node_check.rc is defined and node_check.rc != 0)
      ansible.builtin.shell: |
        set -e
        sudo dnf -y install nodejs
      args:
        executable: /bin/bash

    - name: Install PM2 globally
      when: pm2_check.rc is defined and pm2_check.rc != 0
      ansible.builtin.shell: |
        set -e
        sudo npm install -g pm2
      args:
        executable: /bin/bash

    - name: Ensure 2G swapfile exists (to avoid OOM during npm install)
      when: (swap_status.stdout | trim) == ""
      block:
        - name: Allocate swapfile
          ansible.builtin.command: fallocate -l 2G /swapfile
          args:
            creates: /swapfile
        - name: Set swapfile permissions
          ansible.builtin.file:
            path: /swapfile
            mode: "0600"
        - name: Format and enable swapfile
          ansible.builtin.shell: |
            mkswap /swapfile
            swapon /swapfile

    - name: Install dependencies
      become_user: "{{ app_owner }}"
      ansible.builtin.shell: |
        set -e
        if [ -f package-lock.json ]; then
          npm ci --no-audit --no-fund --prefer-offline
        else
          npm install --no-audit --no-fund --prefer-offline
        fi
      args:
        chdir: "{{ working_dir }}"
        executable: /bin/bash
      environment:
        NODE_OPTIONS: "--max-old-space-size=512"

    - name: Build Next.js app
      become_user: "{{ app_owner }}"
      ansible.builtin.shell: |
        set -e
        npm run build
      args:
        chdir: "{{ working_dir }}"
        executable: /bin/bash

    - name: Start or restart app with PM2
      become_user: "{{ app_owner }}"
      ansible.builtin.shell: |
        set -e
        pm2 start npm --name "nextjs-app" -- run start || pm2 restart nextjs-app
        pm2 save
      args:
        chdir: "{{ working_dir }}"
        executable: /bin/bash
Enter fullscreen mode Exit fullscreen mode

Create Inventory File

Create inventory.ini:

[nextjs_servers]
your-app-server-ip ansible_user=ec2-user ansible_ssh_private_key_file=~/.ssh/your-key.pem
Enter fullscreen mode Exit fullscreen mode

🎯 What this playbook does:
✅ Installs Node.js and PM2
✅ Clones your latest code
✅ Installs dependencies safely
✅ Builds your Next.js app
✅ Starts it with PM2 (keeps running even if SSH disconnects)

Step 4: Test Your Playbook Locally

Before automation, let's make sure everything works:

# Test connection
ansible all -i inventory.ini -m ping

# Run the full deployment
ansible-playbook -i inventory.ini deploy.yml
Enter fullscreen mode Exit fullscreen mode

If everything works, you should see:

  • ✅ All tasks completed successfully
  • ✅ Your Next.js app running on http://your-server-ip:3000

Step 5: Automate with GitHub Actions

Now for the automation magic! Create .github/workflows/deploy.yml in your Next.js repository:

name: Deploy with Ansible

on:
  push:
    branches: [main]
  workflow_dispatch: {}

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: 📥 Checkout repository code
        uses: actions/checkout@v4

      - name: 🔐 Setup SSH key for server access
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p ~/.ssh && chmod 700 ~/.ssh

          # Create temporary file for the key
          TMP_KEY=$(mktemp)
          printf "%s" "${{ secrets.ANSIBLE_SSH_PRIVATE_KEY }}" > "$TMP_KEY"

          # Handle different key formats
          if grep -q "BEGIN .*PRIVATE KEY" "$TMP_KEY"; then
            echo "✅ Found PEM format key"
            cp "$TMP_KEY" ~/.ssh/id_rsa
          else
            echo "🔧 Trying to decode as base64..."
            base64 -d "$TMP_KEY" > ~/.ssh/id_rsa
          fi

          chmod 600 ~/.ssh/id_rsa

          # Validate the key
          if ! ssh-keygen -y -f ~/.ssh/id_rsa >/dev/null 2>&1; then
            echo "❌ SSH key is invalid!"
            exit 1
          fi

          eval "$(ssh-agent -s)"
          ssh-add ~/.ssh/id_rsa
          rm -f "$TMP_KEY"

      - name: 🔒 Add server fingerprints to known hosts
        shell: bash
        run: |
          for host in "${{ secrets.ANSIBLE_HOST }}" "${{ secrets.ANSIBLE_APP_HOST }}"; do
            if [[ -n "$host" ]]; then
              ssh-keyscan -H "$host" >> ~/.ssh/known_hosts 2>/dev/null || true
            fi
          done

      - name: 🚀 Deploy Next.js app via Ansible
        shell: bash
        run: |
          set -euo pipefail

          USER_TO_USE="ec2-user"
          CONTROL_HOST="${{ secrets.ANSIBLE_HOST }}"
          SSH_OPTS="-o StrictHostKeyChecking=no -o ServerAliveInterval=30"

          # Create workspace on control host
          ssh ${SSH_OPTS} "${USER_TO_USE}@${CONTROL_HOST}" \
            "sudo install -d -m 755 -o ${USER_TO_USE} -g ${USER_TO_USE} /home/${USER_TO_USE}/deploy"

          # Upload playbook
          scp ${SSH_OPTS} ansible/deploy.yml "${USER_TO_USE}@${CONTROL_HOST}:/home/${USER_TO_USE}/deploy/"

          # Create inventory
          INVENTORY=$(mktemp)
          cat > "$INVENTORY" <<'INV'
          [nextjs_servers]
          app ansible_host=${{ secrets.ANSIBLE_APP_HOST }} ansible_user=ec2-user ansible_ssh_private_key_file=/home/ec2-user/.ssh/your_key.pem
          INV

          scp ${SSH_OPTS} "$INVENTORY" "${USER_TO_USE}@${CONTROL_HOST}:/home/${USER_TO_USE}/deploy/inventory.ini"
          rm -f "$INVENTORY"

          # Install Ansible if needed
          ssh ${SSH_OPTS} "${USER_TO_USE}@${CONTROL_HOST}" '
            if ! command -v ansible-playbook >/dev/null 2>&1; then
              sudo yum -y install python3-pip
              python3 -m pip install --user ansible
              echo "export PATH=\"$HOME/.local/bin:$PATH\"" >> ~/.bashrc
            fi
          '

          # Run deployment
          ssh ${SSH_OPTS} "${USER_TO_USE}@${CONTROL_HOST}" \
            "PATH=\"\$HOME/.local/bin:\$PATH\" ansible-playbook -i /home/${USER_TO_USE}/deploy/inventory.ini /home/${USER_TO_USE}/deploy/deploy.yml"

          echo "🎉 Deployment completed successfully!"
Enter fullscreen mode Exit fullscreen mode

Add GitHub Secrets

In your GitHub repo, go to Settings → Secrets → Actions and add:

  1. ANSIBLE_SSH_PRIVATE_KEY: Your .pem file content (the whole file!)
  2. ANSIBLE_HOST: Your Ansible Controller's public IP
  3. ANSIBLE_APP_HOST: Your app server's IP

⚠️ Important: Never commit SSH keys to your repository. Always use GitHub Secrets!

Step 6: Deploy and Celebrate! 🎉

Now comes the moment of truth:

  1. Commit and push your changes to the main branch
  2. Watch GitHub Actions run your workflow

GitHub Actions

  1. Visit your app at http://your-server-ip:3000

Nextjs Page

If everything worked, you'll see your Next.js app running!

Troubleshooting Common Issues

"SSH Connection Refused"

  • Check Security Groups allow port 22
  • Verify your SSH key is correct
  • Test manual SSH connection first

"npm install fails with error 137"

This is an out-of-memory error. The playbook includes a swapfile creation to prevent this.

"Playbook not found"

Make sure your file paths in the GitHub Actions workflow match your actual file structure.

Going Beyond: Scale Like a Pro

Deploy to Multiple Servers

Add more servers to your inventory.ini:

[nextjs_servers]
app-server-1 ansible_user=ec2-user
app-server-2 ansible_user=ec2-user  
app-server-3 ansible_user=ec2-user
Enter fullscreen mode Exit fullscreen mode

One command now deploys to all servers! 🚀

Add a Load Balancer

Use AWS Application Load Balancer to distribute traffic across your servers.

Environment Variables

Add environment-specific configs to your playbook:

- name: Create .env file
  copy:
    content: |
      NODE_ENV=production
      DATABASE_URL={{ database_url }}
      API_KEY={{ api_key }}
    dest: "{{ app_dir }}/.env"
Enter fullscreen mode Exit fullscreen mode

What's Next?

This setup gives you a solid foundation, but there's always room to grow:

  • Docker + ECS/EKS for container-based deployments
  • Blue-Green deployments for zero-downtime updates
  • Monitoring with tools like New Relic or Datadog
  • Automated testing before deployment

But honestly? What you've built here can handle most real-world applications. I've used similar setups for production apps serving thousands of users.

Final Thoughts

Remember when deploying meant manually SSH-ing into servers and crossing your fingers? Those days are over.

With this setup, you push code and walk away. Ansible handles the rest. Your app deploys consistently every time, whether it's to 1 server or 100.

The best part? You learned this without becoming a DevOps expert. You're still a frontend/fullstack developer — just one who happens to know how to automate deployments like a pro.

Want to see more DevOps content for developers? Follow me and let me know in the comments what you'd like to automate next!

Originally published at TechByCuong.com

Top comments (0)