Introduction
In the previous blog post, we learned how to create a Next.js application using Nx and set up our development environment. Now, it's time to take our application to the next level by containerizing it with Docker. Containerization allows us to package our application along with its dependencies, ensuring consistent and portable deployments. In this follow-up blog post, we will explore the process of containerizing our Nx + Next.js application and deploying it using Docker.
Table of Contents
- Prerequisites
- Step 1: Preparing the Next.js Application
-
Step 2: Adding a
container
target to the project - Step 2: Creating a Dockerfile
- Step 3: Building the Docker Image
- Step 4: Running the Docker Container
- Conclusion
Prerequisites
Before proceeding, make sure you have the following prerequisites in place:
-
Completed the previous post steps.
Basic understanding of Docker and containerization concepts.
Docker installed on your machine.
Step 1: Preparing the Next.js Application
Let's prepare our Next.js application for containerization.
Good news! There is not much to do here. The @nx/next
plugin already takes care of most of the work for us. When we build our application using:
pnpm exec nx build my-app
You will notice in the dist/apps/my-app
directory that a package.json
file was created. This file will represent a subset of the workspace package.json
containing only and just only the packages needed by our app (and it's workspace dependencies).
dist/apps/my-app/package.json
:
{
"name": "my-app",
"version": "0.0.1",
"dependencies": {
"next": "13.4.1",
"react": "18.2.0",
"react-dom": "18.2.0",
"typescript": "5.1.5"
},
"scripts": {
"start": "next start"
}
}
This generated package.json
will help us to only install the minimum required dependencies needed by the application in our container.
If you are not using static dependency versions in your root package.json
you may want to also generate a lock file to ensure dependency versions in production match with your development environment. To achieve this add the following option to your application build
target:
{
...
"build": {
"executor": "@nx/next:build",
"outputs": ["{options.outputPath}"],
"defaultConfiguration": "production",
"options": {
"outputPath": "dist/apps/my-app"
},
"configurations": {
"development": {
"outputPath": "apps/my-app"
},
"production": {
+ "generateLockfile": true
}
},
"dependsOn": ["build-custom-server"]
},
...
}
Step 2: Adding a container
target to the project
We want to run the container build process the same way as we lint, build and test our app: with a project target. To achieve this, we will make use the awesome @nx-tools/nx-container
Nx plugin.
The @nx-tools/nx-container
Nx plugin provides first class support for Container builds in your Nx workspace. It supports Docker, Podman and Kaniko engines. Leave a star in its repo and take a look there for advanced configuration.
Start by installing the plugin, run:
pnpm add -D @nx-tools/nx-container
Tip: You can optionally follow the docs about using the
@nx-tools/container-metadata
package to enable automatic image tagging with OCI Image Format Specification labels.
Next, let's setup our project to be containerized:
pnpm exec nx g @nx-tools/nx-container:init my-app --template next --engine docker
You will see a new container
target added to the application's project.json
. Let's configure the target as shown below:
apps/my-app/project.json
:
{
...
"targets": {
...
"container": {
"executor": "@nx-tools/nx-container:build",
"dependsOn": ["build"],
"defaultConfiguration": "local",
"options": {
"engine": "docker",
"context": "dist/apps/my-app",
"file": "apps/my-app/Dockerfile"
},
"configurations": {
"local": {
"tags": ["my-app:latest"],
"push": false
},
"production": {
"tags": ["my.image-registry.com/my-app:latest"],
"push": true
}
}
}
},
...
}
You can replace the production
configuration with what better suits your needs. You are also free to add all the necessary configurations.
Understanding our container
target config
We have configured the container
target to make use of Docker as the container engine with some additional options:
context
: we are telling docker to use our app's output directory as the context passed to the image build process. This way we don't waste memory passing the whole monorepo when we only need some specific files.push
: For thelocal
configuration this option is turned off as we don't want to push the built image to the registry by default.file
: Here we specify where to find theDockerfile
used for the container image build, this path is relative to the workspace root.
Step 2: Creating a Dockerfile
A Dockerfile is a text file that contains instructions for building a Docker image. In this step, we will create a Dockerfile for our Next.js application. We'll define the base image, copy the application code, and specify the required dependencies.
# Install dependencies only when needed
FROM docker.io/node:lts-alpine as dependencies
RUN apk add --no-cache libc6-compat
WORKDIR /usr/src/app
COPY .npmrc package.json ./
RUN npm install --only=production
# Production image, copy all the files and run next
FROM docker.io/node:lts-alpine as runner
RUN apk add --no-cache dumb-init
ENV NODE_ENV production
ENV PORT 3000
ENV HOST 0.0.0.0
ENV NEXT_TELEMETRY_DISABLED 1
WORKDIR /usr/src/app
# Copy installed dependencies from dependencies stage
COPY --from=dependencies /usr/src/app/node_modules ./node_modules
# Copy built application files
COPY ./ ./
# Run the application under "node" user by default
RUN chown -R node:node .
USER node
EXPOSE 3000
# If you are using the custom server implementation:
CMD ["dumb-init", "node", "server/main.js"]
# If you are using the NextJS built-int server:
# CMD ["dumb-init", "npm", "start"]
Important: If you are also using
pnpm
and enabled thegenerateLockfile
option forbuild
target, you may want to first install pnpm in the dependencies stage to make use of the generatedpnpm-lock.yaml
file.You will also need to copy the
pnpm-lock.yaml
before running the installation command:+ RUN npm install -g pnpm - COPY .npmrc package.json ./ + COPY .npmrc package.json pnpm-lock.yaml ./ - RUN npm install --only=production + RUN pnpm install --frozen-lockfile --prod
To improve the efficiency of our Docker builds and reduce the image size, we are leveraging the concept of multi-stage builds. Using a multi-stage build allow us to separate the dependencies installation environment from the runtime environment. This way, as an example, we can remove sensitive data like private registries authentication tokens from our app runtime container.
Step 3: Building the Docker Image
With the Dockerfile in place and our container
target configured, we'll proceed to build the Docker image. We'll use the container
target to execute the build process, which involves pulling the base image, installing dependencies, and creating the final image.
To build our image, run:
pnpm exec nx container my-app
This will first build our application and it's dependencies prior to run the docker container build. To visualize this tasks dependencies you can run:
pnpm exec nx container my-app --graph
You will find the following task dependency structure.
Step 4: Running the Docker Container
Once the Docker image is built, we'll run it as a container to verify that our application is working correctly within the containerized environment.
To start our container, run:
docker run -p 3000:3000 -t my-app:latest
You will get and output like:
➜ docker run -p 3000:3000 -t my-app:latest
shared-util-nextjs-server
[ ready ] on http://0.0.0.0:3000
You can now visit http://localhost:3000 to access your NextJS application.
You can even send an HTTP request to your exposed API endpoints:
➜ curl http://localhost:3000/api/hello
Hello, from API!
Great! 🎉
Conclusion
Containerization provides numerous benefits, including improved portability, scalability, and reproducibility of our applications. In this follow-up blog post, we've learned how to containerize our Nx + Next.js application using Docker. By leveraging Docker, we can simplify the deployment process and ensure consistent behavior across different environments.
Stay tuned for more exciting topics as we continue our journey with Nx, Next.js, and Docker!
You can find all related code in the following Github repo:
sebastiandg7 / nx-nextjs-docker
An Nx workspace containing a NextJS app ready to be deployed as a Docker container.
Nx + Next.js + Docker
This repository contains the code implementation of the steps described in the blog posts titled:
- Nx + NextJS + Docker - The Nx way: Creating the NextJS application.
- Nx + NextJS + Docker - The Nx way: Containerizing our application
Overview
The blog post provides a detailed guide on setting up a Next.js application using Nx and Docker, following best practices and leveraging the capabilities of the Nx workspace.
The repository contains all the necessary code and configuration files to follow along with the steps outlined in the blog post.
Prerequisites
To successfully run the Next.js application and Dockerize it, ensure that you have the following dependencies installed on your system:
- Docker (version 23)
- Node.js (version 18)
- pnpm (version 8)
You can alternatively use Volta to setup the right tooling for this project.
Getting Started
To get started, follow the steps below:
-
Clone the…
Top comments (11)
you are AWESOME!!!!!!!!!!!!!!!!!!!!
I'm glad it was helpful! 😀
I got this to work by building my image on my Docker Desktop and deploying it to Docker Hub. Now, I want to do this using Skaffold. How would any of this code need to change for that?
Since Skaffold gives a random name for every container I build, would this not work, given that you have to specify the container name beforehand in the Nx project.json file in
containers
>configuration
>production
?If so, how do you get around this?
Try to build the Dockerfile using just docker and it fails.
Hey. Can you share what command did you use?
docker build
It works when using the nx-container command, but docker files should stand on their own.
Aboslutely! The equivalent build command to the
container
target would be:From the workspace root:
docker buildx build --file apps/my-app/Dockerfile --tag my-app:latest dist/apps/my-app
You first need to build the app as Nx does prior to building the docker image.
really good!!
I have a question: how to config in project.json when I have one app but want to build multi docker image from this app with different environment?
You could add different configurations to the
container
target with different Dockerfiles, tags, etc.Great article. Keep more coming.
I'm need help to configure Docker Dev Containers for programming with Nx Angular