Understanding Next.JS Docker Images

If you've tried to containerize a NextJS app, you've probably found the official documentation  to be a bit lacking. Especially for beginners, the provided Dockerfile  might be confusing. In this post, we'll go over the Dockerfile and explain what exactly is going on!

The Dockerfile

Let's start by looking at the Dockerfile provided by the wonderful NextJS  team.

The Dockerfile can be broken down into 4 parts: the base image, the dependency installation, the build, and the runtime.

The Base Image

The first part (and first line!) of the Dockerfile is the base image that the Docker Image is built on top of. Similar to an operating system like Linux or Windows, the base image provides the foundation and structure for the rest of the image. In this case, we usenode:lts-alpine, which is a small but powerful image that contains NodeJS. The lts refers to the version of NodeJS. If you want to use a different version, you could replace it with any applicable version!

Dependency Installation

As always with Next.JS projects, we first need to install our dependencies. This is done in the next block. But before we install our dependencies, we see the line:

RUN apk add --no-cache libc6-compat

Why is this line here? Well, the node:lts-alpine image is based on Alpine Linux, which is a very small Linux distribution. However, it is so small that it doesn't have all the libraries thatsome NodeJS packages need. The libc6-compatpackage provides some of these libraries, reducing the chance of errors when installing dependencies. This line isn't always needed, but it's a good idea to include it just in case. If you want a more in-depth explanation of why this might be needed, check out this Github Repo.

Now we can finally start working on our dependencies! To keep everything neat and tidy, we first create a new directory called /appand set it as our working directory. Then, we copy over thepackage.json, and package-lock.json, files.

RUN npm ci

This block of code it will run npm ci.

The Build

The next part of the Dockerfile contains the actual build process where we compile our NextJS app.

As before, we first start a new image layer and set our working directory to /app. Then, we copy over thenode_modules folder from our previous image layer. After copying the node_modules folder, we copy over the rest of our app. This is done in two steps to improve build times. If we copied over the entire app first, then every time we made a change to our app, we would have to reinstall our dependencies. By copying over thenode_modules folder first, we can skip the dependency installation step if we haven't changed our dependencies! Smart, right?

Finally, we run yarn build to execute the command that is defined in our package.json file. This command is usuallynext build, but it can be changed to whatever you want. It doesn't really matter if we use yarn or npmhere, because we already installed our dependencies in the previous step and the package manager doesn't really matter for the build process!

The Runtime

And finally, we are done with installing our dependencies and building our app! The last part of the Dockerfile is the runtime, where we actually run our app. This part is a bit longer, so let's go through it step by step.

Again, we start by creating a new image layer and setting our working directory to /app. We then set the NODE_ENVenvironment variable to PRODUCTION. This signals to NextJS that we are running in production mode, which will improve performance. This can also affect other parts of your app and NodeJS. Check out this awesome documentation page  for more information!

Next, we create a new group and user. This is done to improve security. If we didn't do this, our app would run as root, which can be a security issue. Generally, you want to try to follow the "Principle of least privilege"  , which states that you should only give your app the permissions that it needs. In this case, our app doesn't need root permissions, so we create a new user and group for it. We then finally switch to this new user with USER nextjs.

Now we can finally copy over the build artifacts from the previous image layer. We first copy over the ./public folder which includes all of our static assets. Then, we copy over the./.next/standalone and ./.next/static folders, which include all of our compiled code. This step will only work if you set your output mode in your Next.JS Config  . If you don't set your output mode, your dependencies will not be included!

At this point we have improved security, enabled production mode, and copied over all the build artifacts. The next 3 lines are all about networking and making our Next.JS app available to the the network.

We first expose port 3000 to the network withEXPOSE 3000. This doesn't actually do anything, but it's a good practice to include it so that other developers know which port the Docker Container will be running on. Next, we set the PORTenvironment variable to 3000. This is used by NextJS to determine which port to run on. Finally, we set the HOSTenvironment variable to localhost.

The last line is the actual command that is run when the Docker Container is started and is not executed during the image build process. Since we compiled the Next.JS app to a standalone file, we can simply start it with node server.js. That's it! We're done! 🎉🎉🎉

Bonus

GitHub Actions Build and Push

We will be using GitHub Actions to build the image in every PR and then build and push to GitHub Registry on main. The workflow can be found in docker-publish.yml

Conclusion

I hope this post helped you understand the NextJS Dockerfile a bit better.