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!
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 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 use
node:18-alpine, which is a small but powerful image that contains NodeJS. The
18 refers to the version of NodeJS. If you want to use a different version, you could replace the
18 with a
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:18-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 that some NodeJS packages need. The
libc6-compat package 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
/app and set it as our working directory. Then, we copy over the
Now you might be looking at your own Next.JS app and only see one or two of these files. That's okay! The Dockerfile is designed to work with all three of the most popular NodeJS package managers:
Because this Dockerfile is designed to work with all three package managers, the next part is also a bit more complicated:
RUN \ if [ -f yarn.lock ]; then yarn --frozen-lockfile; \ elif [ -f package-lock.json ]; then npm ci; \ elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i --frozen-lockfile; \ else echo "Lockfile not found." && exit 1; \ fi
This block of code checks which package manager you're using by checking which lockfile exists. If you're using
yarn, it will run
yarn --frozen-lockfile. If you're using
npm, it will run
npm ci. If you're using
pnpm, it will run
yarn global add pnpm && pnpm i --frozen-lockfile. If you're using something else, it will print an error message and exit.
If you know which package manager you're using, you can simplify this part of the Dockerfile. For example, if you're using
npm, you can remove the
pnpm-lock.yaml files and replace the entire block with:
COPY package.json package-lock.json* ./ RUN npm ci
Try it out and see if it works! If not, feel free to write a comment below and I'll be happy to help you out :)
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 the
node_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 the
node_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 usually
next build, but it can be changed to whatever you want. It doesn't really matter if we use
npm here, because we already installed our dependencies in the previous step and the package manager doesn't really matter for the build process!
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_ENV environment 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
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/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 with
EXPOSE 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
PORT environment variable to
3000. This is used by NextJS to determine which port to run on. Finally, we set the
HOST environment variable to
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! 🎉🎉🎉
That was a long one, good job! I hope this post helped you understand the NextJS Dockerfile a bit better. If you have any questions, feel free to leave a comment below and I'll be happy to help you out! If you have any suggestions for future posts, I'd love to hear them as well. Thanks for reading! 😊
Want to host your next cool dockerized Next.JS project? Check out Sliplane!