DEV Community

Cover image for How to deploy a Nextjs app with Kamal 2.4, AWS ECR, and Github Actions
Derick Zihalirwa
Derick Zihalirwa

Posted on • Edited on

How to deploy a Nextjs app with Kamal 2.4, AWS ECR, and Github Actions

#tutorial #kamal #nextjs #webdev

Why Use Kamal for Deployment?

So, why pick Kamal for your deployments?

Simple: it makes the process smooth, fast, and reliable—without locking you into a complicated toolchain. Here’s what makes Kamal shine:

  • Readable YAML configs: Easy to write, easy to understand.
  • First-class Docker support: Get consistent builds wherever you deploy.
  • Rolling deployments: No downtime. No late-night fire drills.
  • Built-in health checks: Kamal keeps an eye on your app so you don’t have to.

Whether you're shipping fast or scaling up, Kamal helps you stay in control.

What You’ll Need Before You Start

Before jumping in, make sure your dev environment’s good to go:

  • An AWS account, with the CLI set up
  • Docker installed (and basic CLI comfort)
  • Kamal version 2.4 or higher
  • A working Next.js app
  • Some GitHub Actions knowledge

Step 1: Initialize Kamal in Your Project

Start by initializing Kamal in your app repo. Run:

kamal init
Enter fullscreen mode Exit fullscreen mode

This sets up a .kamal directory with the core config files you’ll customize next.

Project Structure Overview

Here’s what your project directory should look like after setup:

project-root/
├── .kamal/                   # Kamal deployment config
│   ├── deploy.yml            # Main deployment settings
│   └── secrets               # Environment secrets
├── .github/workflows/        # CI/CD pipelines
│   └── release-deploy.yml    # GitHub Actions workflow
├── Dockerfile                # Production build setup
├── package.json              # Dependencies
├── yarn.lock                 # Lockfile
├── .env                      # Local environment variables
├── public/                   # Static assets
└── .next/                    # Compiled Next.js output
Enter fullscreen mode Exit fullscreen mode

Example deploy.yml for Kamal

Here’s a sample deploy.yml config tuned for staging:

defaults:
  service: web-app
  image: example/web-app

servers:
  web:
    - 192.168.1.1  # Replace with your staging server IP

ssh:
  user: ubuntu
  keys: ["~/.ssh/example-key.pem"]

proxy:
  ssl: false
  app_port: 3000
  host: stagingapp.example.io
  healthcheck:
    path: /
    interval: 3
    timeout: 30

registry:
  server: 123456789012.dkr.ecr.us-west-1.amazonaws.com
  username: AWS
  password: <%= %x(aws ecr get-login-password) %>

builder:
  arch: amd64
  context: .

env:
  clear:
    NEXT_PUBLIC_APP_BACKEND_URL: https://staging.api.example.io
    NEXT_PUBLIC_APP_PUBLIC_IP_API: https://pro.ip-api.com/json/?key=dummykey
Enter fullscreen mode Exit fullscreen mode

Building a Dockerfile for Next.js

Here’s a lean, production-ready Dockerfile for a Next.js app:

FROM node:lts-bookworm-slim AS base

FROM base AS deps
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
ARG NEXT_PUBLIC_APP_BACKEND_URL
ARG NEXT_PUBLIC_APP_PUBLIC_IP_API
ENV NEXT_PUBLIC_APP_BACKEND_URL=$NEXT_PUBLIC_APP_BACKEND_URL
ENV NEXT_PUBLIC_APP_PUBLIC_IP_API=$NEXT_PUBLIC_APP_PUBLIC_IP_API

COPY . .
RUN yarn run build

FROM base AS release
WORKDIR /app
ENV NEXT_TELEMETRY_DISABLED=1
COPY --from=deps /app/node_modules ./node_modules
COPY --from=deps /app/package.json ./package.json
COPY --from=deps /app/.next ./.next
COPY --from=deps /app/public ./public

EXPOSE 3000
CMD ["yarn", "start"]
Enter fullscreen mode Exit fullscreen mode

This sets you up for reproducible builds and fast deployment.

Automating Deployments with GitHub Actions

Want your app to deploy automatically when a new release is published? Here’s a GitHub Actions workflow that gets the job done:

name: Release Deploy

on:
  release:
    types: [published]

permissions:
  contents: read
  packages: write
  id-token: write

env:
  ECR_REPOSITORY: example/web-app

jobs:
  package:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Create .env file
        run: |
          echo "${{ secrets.PROD_ENV_FILE }}" > .env

      - name: Configure AWS
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-1

      - name: Login to ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build & Push Docker Image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: ./Dockerfile
          platforms: linux/amd64
          push: true
          tags: |
            ${{ steps.login-ecr.outputs.registry }}/${{ env.ECR_REPOSITORY }}:${{ github.sha }}
Enter fullscreen mode Exit fullscreen mode

This pipeline checks out your code, configures AWS credentials, builds the Docker image, and pushes it straight to your ECR registry—all triggered by a GitHub release.

Wrapping Up

And there you have it: a solid deployment workflow using Kamal 2.4, Docker, and GitHub Actions.

You’ve got:

  • A clean, reproducible setup
  • Auto-deployments on release
  • A scalable, self-hosted Next.js app on AWS

No vendor lock-in. No drama. Just fast, predictable deployments.

Top comments (0)