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
  • Understanding our container target config
• 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:

1. Completed the previous post steps.
   

   

   Nx + NextJS + Docker: Creating the NextJS application

   Sebastián Duque G ・ Jun 28 ・ 6 min read

   #nextjs #nx #docker #tutorial

2. Basic understanding of Docker and containerization concepts.

3. 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 the local 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 the Dockerfile 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 the generateLockfile option for build target, you may want to first install pnpm in the dependencies stage to make use of the generated pnpm-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: