How to Run Next JS App with Docker and Static Site Generation

Next.js is a popular React-based framework for building server-rendered, statically generated, and performance-optimized websites and applications. It's a great choice for developers who want to create fast, scalable, and maintainable web projects.

To run a Next.js app with Docker and static site generation, you'll need to create a Dockerfile in the root of your project. This file will contain instructions for Docker to build and run your application.

Docker is a containerization platform that allows you to package your application and its dependencies into a single container, making it easy to deploy and manage your project across different environments.

Static site generation is a crucial step in running a Next.js app. It's a process that can be run at build time or deferred until after deployment.

You can run static site generation at build time, but this approach has its downsides. Your deployment machine will need enough memory to run a build, which can be a challenge if you're working with limited resources.

If you do decide to run static site generation at build time, you'll need to ensure that your deployment machine has sufficient memory. You can check the recommended memory settings by visiting the Fly documentation on scaling memory and swap size.

Alternatively, you can defer static site generation until after deployment. This approach has its own set of trade-offs, including the need for additional memory and potential downtime while the site is being generated. If you're running multiple machines, you'll also need to consider the increased time it takes for changes to be fully deployed.

To help you visualize the trade-offs, here are some key considerations when deciding whether to run static site generation at build time or after deployment:

You can use a Dockerfile generator to get started with creating a Dockerfile for your Next.js or Bun application. This can save you time and effort.

The Dockerfile generator can be run using npx dockerfile for Node applications or bunx dockerfile for Bun applications.

You'll see the Dockerfile generator referenced throughout this article for various use cases.

Static site generation can be done in different ways, but one approach is to defer the build step until after deployment. This allows your build to access deployment secrets and environment variables.

One way to do this is by replacing the entry point in your Dockerfile with a script that runs npm build before starting the server. This can be done automatically by the Dockerfile generator.

This approach has some downsides, though. For one, your deployment machines will need enough memory to run a build, which can be a challenge if you're working with limited resources.

You'll also need to adjust the grace period for any HTTP service checks, as the site will be inaccessible for a period of time while it's being generated.

If you're running multiple machines, the static site generation will be run on each one, increasing the total time before changes are fully deployed.

Here are some things to consider when deciding whether to defer static site generation:

Server Side Rendering is a powerful feature that can take your website to the next level. Every hybrid Next.js deployment comes with a managed backend, which is automatically available in all plans.

Having a managed backend is great, but you can fine-tune performance and take more control of the backend by assigning a custom backend to your site. This can be done without experiencing any downtime.

Your site will experience no downtime if you switch between a managed backend to a linked backend. This means you can experiment with different backend configurations without worrying about your site going down.

You can add a new page to your Next.js app by creating a new file in the pages directory.

Next.js apps use a file-based routing system, so you can create a new page by creating a new file in the pages directory.

To add a new API route, you'll need to create a new file in the pages/api directory.

API routes in Next.js are server-side routes that can be used to handle API requests.

To add a new API route, you'll need to export a function from the file that will be called when the route is accessed.

To set up logging for your Next.js app, you'll want to follow best practices for server API troubleshooting. This involves adding logging to the API to catch any errors that may occur.

For Azure, you'll use Application Insights for logging. To preload the Application Insights SDK, you'll need to create a custom startup script.

Here are some resources to get you started:

Next.js versions require specific Node.js versions, so you'll need to set the engines property in your package.json file to designate a version. This ensures compatibility and prevents errors.

To configure a specific Node version, you can add a line like "engines": {"node": "14.x"} to your package.json file. This tells Next.js to use Node.js version 14.

Setting environment variables is crucial for Next.js applications. Next.js uses environment variables at build time and at request time.

For static page generation, you need to set environment variables within the build task. This ensures that your application has the necessary settings to generate static pages correctly.

When deploying your application, set environment variables in the Environment variables of your Azure Static Web Apps resource. This way, your application can access the necessary settings at request time.

Environment variables are used to support both static page generation and dynamic page generation with server-side rendering.

Enabling logging for Next.js is crucial for server API troubleshooting. You can use Application Insights for logging on Azure.

To preload the Application Insights SDK, you'll need to create a custom startup script. This is a common approach for Next.js applications.

The custom startup script can include the example preload script for Application Insights + Next.js. This script helps set up logging from the start.

For more information on preloading with Next.js, check out the GitHub issue. This provides additional guidance on the process.

Here are some resources to get you started: