How to Setup EC2 for Dockerized Next.js Deployment
Introduction
Next.js is great serve-side oriented frontend framework that makes building SEO-friendly websites easier.
Deploying it is trickier than it needs to be, I understand Vercel needs to make money off of their creation. If you need an alternative way to deploy your website, dockerizing it will remove few of the headaches.
In this example, I'm using AWS EC2 for deployment but most of the steps would work on any other Linux VPS (Like Linode and etc)
Prerequisites
Step 1: Prepare Your Next.js Application
Create Dockerfile for Next.js application with the following content:
FROM node:18-alpine AS base
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
elif [ -f package-lock.json ]; then npm ci; \
elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
else echo "Lockfile not found." && exit 1; \
fi
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN \
if [ -f yarn.lock ]; then yarn run build; \
elif [ -f package-lock.json ]; then npm run build; \
elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
else echo "Lockfile not found." && exit 1; \
fi
FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
RUN mkdir .next
RUN chown nextjs:nodejs .next
RUN chmod -R +x ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
ENV PORT=3000
CMD ["node", "server.js"]
Let's connect to the EC2 instance using SSH.
ssh -i your-key-file.pem ec2-user2@ec2-YOUR-PUBLIC-IP.us-east-1.compute.amazonaws.com
Install tools
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
apt-cache policy docker-ce
sudo apt install -y docker-ce
docker -v
sudo systemctl status docker.service
sudo systemctl start docker.service
In case you hate prefixing every docker command with sudo you can do the following:
sudo usermod -aG docker $USER
su - $USER
Step 3: Deploy Docker Image to Docker hub or Github containers
To deploy the image of your dockerized project, you need to push it to a container repo like Docker Hub or Github containers. In this example, I'm using Github containers.
First we need to authenticate our local docker with our Github containers repo. We need an API token to use as password with docker login.
Go to Gihtub.com Click on your profile picture on the top right.
Click Settings
Click Developer settings at the bottom of the left sidebar
Click Personal access tokens to expand
Click Tokens (classic)
Click Generate new token dropdown
Click Generate new token (classic) option
Type the name of your project in the Node input
Check write:packages and delete:packages checkboxes
Finally click Generate token button near the bottom to complete this
sudo docker login ghcr.io
Username: your-github-username
Password: api-token-generated-above
Note: the generated API key is only shown once, so you need to keep it in a safe place to use it later to login to your Github container repository.
Let's create the images to deploy to our container repo we setup above.
docker build --platform linux/amd64 -t ghcr.io/your-github-username/project-name:v0.0.1 .
To use the image locally, let's stop if there any previous image running:
docker stop my-container-name
docker rm my-container-name
docker run --rm --name my-container-name -d -p 3000:3000 ghcr.io/your-github-username/project-name:v0.0.1
After testing and making sure we have the container working as expected, let's push it to Github so we can pull from our EC2 server.
docker push ghcr.io/your-github-username/project-name:v0.0.1
Let's connect to the EC2 thourgh SSH again if not still connected:
ssh -i your-key-file.pem ec2-user2@ec2-YOUR-PUBLIC-IP.us-east-1.compute.amazonaws.com
Let's pull the docker image from github. NOTE: you need to login using the above docker login step and use the same username and API-token as the password.
sudo docker pull ghcr.io/your-github-username/project-name:v0.0.1
Then let's run a container from the docker image we downloaded.
sudo docker run --rm --name my-container-name -d -p 3000:3000 ghcr.io/your-github-username/project-name:v0.0.1
Step 4: Implement Production Optimizations
Setup NGINX
If you don't already have nginx installed, let’s quickly do that
sudo apt update
sudo apt install -y nginx
Let's create a config file for our site for nginx to the HTTP handle requests
sudo touch /etc/nginx/sites-available/my-site-domain.com
sudo nano /etc/nginx/sites-available/my-site-domain.com
Then copy the following content in the file you just opened.
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _ www.my-site-domain.com.com my-site-domain.com.com;
error_log /var/log/nginx/error.log warn;
access_log /var/log/nginx/access.log;
root /var/www/html;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $http_host;
proxy_redirect off;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
We need to link the config file to a file in sites-enabled folder. Creating a link file helps you keep the config file and be able to enable/disable that config by creating or removing the link file, while keeping the actual config file in sites-available.
sudo ln -s /etc/nginx/sites-available/my-site-domain.com /etc/nginx/sites-enabled/my-site-domain.com
Generate SSL Certificates with Certbot
There are other ways to setup SSL on AWS but I like a portable solution that can be used on any Linux VPS. So, we're going to use Let's Encrypt Certbot tool to generate SSL certificates.
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
Common Troubleshooting
The issue I always find is when forget to prefix sudo in docker commands, so if you didn't add docker user to the sudo group, you might get an issue like
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock:
The error doesn't give a suggestion to why this is happening so you might need to run the command again with sudo or follow last part of installing docker above.
Conclusion
Deploying Next.js apps isn't hard as we showed above but there are no clear guides available. This was the only way that worked for me and I thought I have to share with the community as it might save you sometime. If you have any suggestions of how we can improve the above guide, please feel free to share them.
Additional Resources