Nx + NextJS + Docker: Containerizing our application
Published: 2023-06-28 19:36:46

## 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](#prerequisites)
- [Step 1: Preparing the Next.js Application](#step-1-preparing-the-nextjs-application)
- [Step 2: Adding a `container` target to the project](#step-2-adding-a-container-target-to-the-project)
  - [Understanding our `container` target config](#understanding-our-container-target-config)
- [Step 2: Creating a Dockerfile](#step-2-creating-a-dockerfile)
- [Step 3: Building the Docker Image](#step-3-building-the-docker-image)
- [Step 4: Running the Docker Container](#step-4-running-the-docker-container)
- [Conclusion](#conclusion)

## Prerequisites

Before proceeding, make sure you have the following prerequisites in place:

1. Completed the previous post steps.
  {% embed https://dev.to/sebastiandg7/nx-nextjs-docker-the-nx-way-creating-the-nextjs-application-1efl %}

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:

```bash
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`:
```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:

```diff
{
    ...
    "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](https://github.com/gperdomor/nx-tools) and take a look there for advanced configuration.

Start by installing the plugin, run:

```bash
pnpm add -D @nx-tools/nx-container
```

> **Tip:** You can optionally follow [the docs](https://github.com/gperdomor/nx-tools/blob/main/packages/nx-container/README.md#setting-up-the-container-plugin) about using the `@nx-tools/container-metadata` package to enable automatic image tagging with [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/main/annotations.md) labels.

Next, let's setup our project to be containerized:

```bash
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`:
```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.

```Dockerfile
# 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:
> ```diff
> + 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:

```bash
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:

```bash
pnpm exec nx container my-app --graph
```

You will find the following task dependency structure.

![Task dependency graph of the container target for the my-app project](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f2beompojkigizs3b1yt.png)

## 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:

```bash
docker run -p 3000:3000 -t my-app:latest
```

You will get and output like:

```bash
➜ 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.


![nextjs application running inside a docker container](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s1n50nfn0bx0qy1abks0.png)

You can even send an HTTP request to your exposed API endpoints:

```bash
➜ 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:

{% github https://github.com/sebastiandg7/nx-nextjs-docker %}