How to Deploy Next.js Applications with Docker
Tags: nextjs, docker, devops
Published: 2024-02-23 16:35:18

Next.js is the modern open source React.js framework officially support by the React team and Vercel. Most developers choose to deploy Next.js through Vercel, but a standalone export option is available for other platforms. Docker is the industry standard for developing, testing, and shipping production software. It's more lightweight than a virtual machine and portable across cloud vendors like AWS, Digital Ocean, Azure, Vercel, Netlify, and much more.

## Step 1: Preparation
Add the following snippet to your `next.config.js` file to enable `standalone` output for Docker.
```js
// next.config.js
module.exports = {
  // ... rest of the configuration.
  output: "standalone",
};
```

Test your application as it would be in production using `next build` and running `node server.js` in `.next/standalone/`. This way we can catch any errors before moving our code into a production environment.

[Install Docker on your development system.](https://docs.docker.com/get-docker/)

## Step 2: Adding the Dockerfile
Create a `Dockerfile` file at the root of your Next.js application and copy the following code.

*Note that if you're using Windows, pnpm won't work properly, because Docker will try to use symlinks in your `node_modules` folder, so I recommend using Yarn or NPM.*

```Dockerfile
FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi


# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED 1

RUN \
  if [ -f yarn.lock ]; then yarn run build; \
  elif [ -f package-lock.json ]; then npm run build; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
  else echo "Lockfile not found." && exit 1; \
  fi

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000
# set hostname to localhost
ENV HOSTNAME "0.0.0.0"

# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
CMD ["node", "server.js"]
```

> This `Dockerfile` script will run several stages and cache them appropriately to reduce image build times. `FROM base AS deps` install your dependencies using whichever package manager's lockfile you've used during development, `FROM base AS builder` copies your `node_modules` and builds the application, `FROM base as runner` will execute on the end server and run your app. You can find an example project [here](https://github.com/vercel/next.js/tree/canary/examples/with-docker).

## Step 3: Building and Testing the Docker Image
Now run `docker build -t {image-name} .` and don't forget the `.`! 

Before you deploy, it's important to test your docker image with the correct environment variables. Run `docker run -p 3000:3000 {image-name}` to test your application at `localhost:3000`. If you want to test on a different port, use `docker run -p {port}:3000 {image-name}`.

> If you're deploying to Digital Ocean, your image name will look like `registry.digitalocean.com/your-registry/name`. See [their docker registry documentation](https://docs.digitalocean.com/products/container-registry/) for more details.

If you have any questions, comments, or concerns, feel free to comment them!