Language and Framework Guides
Run a NextJS Container App
24 min
back4app containers is a powerful platform for hosting next js applications with its ability to automatically deploy dockerized next js apps, you can launch your project in a scalable and flexible environment with ease in this guide, we will walk you through the process of preparing and deploying your next js application on back4app containers, covering everything from simple projects to more complex setups we will begin with the necessary preparations, then move on to dockerizing the application, testing it locally, pushing the project to github, setting up the project on back4app containers, monitoring deployment, and troubleshooting common issues if you have any questions or comments, feel free to join the conversation in the #containers channel on the back4app community on slack anytime you can also contact us at community\@back4app com at any time, if you want to check a sample working next js project on back4app containers, go to https //github com/templates back4app/containers nextjs sample https //github com/templates back4app/containers nextjs sample 1 prepare your next js application a project structure verify that your next js application follows a proper directory structure, with all necessary files and folders, such as pages , public , components , and styles , organized appropriately the main entry point for your application should be the pages/index js or pages/index jsx file b dependencies check if all required dependencies are listed in the package json file, including their correct versions ensure that you have installed all dependencies using npm install or yarn install to generate a package lock json or yarn lock file c build process for more complex projects that involve a build process, ensure that your build scripts and configurations (e g , webpack, babel, or next js) are properly set up you should be able to run the build process locally without any issues d environment variables if your application relies on environment variables, ensure that you have a env file with the necessary variables defined when deploying to back4app containers, you will need to configure these environment variables in the deployment settings e server setup (if applicable) if your next js application includes a custom server (e g , express), make sure it is correctly set up and configured to serve your next js application test your server locally to ensure it works as expected f application optimization optimize your next js application by minimizing bundle sizes, using code splitting, and implementing performance best practices use tools like lighthouse to audit your application and address any performance or accessibility issues g cross browser compatibility test your application across multiple browsers and devices to ensure proper rendering and functionality once you have thoroughly reviewed and prepared your next js application, you can proceed to the next step, which is creating a dockerfile for your project 2 dockerization dockerizing a next js application involves creating a dockerfile in the root directory of your project the dockerfile contains instructions to build a docker image of your application, which can then be deployed to back4app containers here's a detailed explanation of how to create a dockerfile for a typical next js application 1 create a new file named dockerfile (without any file extension) in the root directory of your next js application 2 define the base image start the dockerfile by specifying a base image using the from command for a typical next js application, the base image should be a node js image, e g , node 14 or node 16 from node 14 3 set the working directory use the workdir command to set the working directory for your application within the docker container this is where your application files will be stored and executed workdir /app 4 copy package json and package lock json copy the package json and package lock json files from your local machine to the docker container using the copy command these files are required to install your application's dependencies copy package json / 5 install dependencies use the run command to install your application's dependencies from the package json file this is typically done using npm ci, which installs the exact dependency versions specified in the package lock json file run npm ci 6 copy the rest of the project files use the copy command again to copy the remaining files and folders from your local machine to the docker container copy 7 build the next js application add a run command to build your next js application using your build script, typically npm run build this generates a production ready version of your next js application in the next folder run npm run build 8 configure the server you need a server to serve your built next js application one common choice is the built in next js server first, install it globally in the docker container using the run command run npm install g next 9 expose the server port use the expose command to specify the port on which your server will run inside the docker container for example, you can use port 3000 expose 3000 10 start the server use the cmd command to specify the command that starts the server to serve your built next js application with the built in next js server, you can specify the start script and the port number cmd \["next", "start", " p", "3000"] the complete dockerfile for a typical next js application should look like this from node 14 workdir /app copy package json / run npm ci copy run npm run build run npm install g next expose 3000 cmd \["next", "start", " p", "3000"] another dockerfiles examples you can use as a reference example 1 using an nginx server if you prefer to use an nginx server to serve your next js application, you can create a multi stage dockerfile in this case, you will first build the next js application and then copy the generated files to the nginx server \# stage 1 build the next js application from node 14 as builder workdir /app copy package json / run npm ci copy run npm run build \# stage 2 set up the nginx server from nginx\ stable alpine copy from=builder /app/ next /usr/share/nginx/html copy from=builder /app/public /usr/share/nginx/html/ next/static copy nginx conf /etc/nginx/conf d/default conf make sure to create an appropriate nginx conf file to configure the nginx server properly example 2 using a custom server if you have a custom server set up for your next js application, you can modify the dockerfile accordingly here's an example using a custom server js file from node 14 workdir /app copy package json / run npm ci copy run npm run build expose 3000 cmd \["node", "server js"] in this example, the custom server is started with the node server js command instead of using the next js server 3 build and run the docker container after creating the dockerfile, you can build the docker image and run a container from it use the following commands to build and run the container docker build t your image name docker run p 3000 3000 your image name replace "your image name" with a name for your docker image once the container is running, you can access your next js application at http //localhost 3000 http //localhost 3000 in your web browser 4 test your project locally before deploying your next js application on back4app containers, it's important to test it locally using docker this helps ensure that your application runs as expected and helps you identify and fix any issues before deployment build the docker image for your next js application in your terminal, navigate to your project's root directory and run the following command, replacing your app name with the name of your application docker build t your app name run the docker container locally next, run the following command to start the docker container locally this command maps the container's exposed port (e g , 3000) to a port on your local machine (e g , 3000) docker run p 3000 3000 your app name test your application open a web browser and navigate to http //localhost 3000 http //localhost 3000 to view your next js application make sure everything works as expected if you encounter any issues, address them before moving on to the next step 5 push your project to github create a gitignore file in your project's root directory to exclude unnecessary or sensitive files from your repository (e g , node modules , env , build , etc ) initialize a git repository, commit your project files, and push them to a remote repository (e g , on github) git add git commit m "initial commit" git remote add origin \<your remote repo url> git push u origin master 6 deploy your application on back4app containers after creating your back4app account you can follow the steps listed on the docs 1 connect you github repo with back4app https //www back4app com/docs containers/integrate with github 2 prepare your project for deployment https //www back4app com/docs containers/prepare your deployment in summary containers will follow the instructions detailed on your dockerfile and start to create your app 7 monitor deployment and address possible errors keep an eye on the deployment logs and status on the back4app containers dashboard address any errors or issues that arise during deployment in case of more complex projects, ensure that all necessary services (such as databases or external apis) are correctly configured and accessible 8 troubleshooting common problems common deployments errors when running a next js app on back4app containers are listed here https //www back4app com/docs containers/troubleshooting other possible common errors when deploying a next js application are incorrect port configuration next js applications should be configured to run on a specified port when deployed on back4app containers if the application is still not accessible, check the dockerfile to make sure the correct port is exposed (e g , expose 3000 for port 3000) incompatible or missing dependencies ensure that all required dependencies are listed in the package json file and that their versions are compatible with each other and your application code missing or incompatible dependencies can lead to runtime errors invalid environment variables or configuration check if your application relies on specific environment variables or configuration files, and ensure they are correctly set up in the back4app containers environment set any necessary environment variables in your dockerfile using the env command application crashes or unhandled exceptions unhandled exceptions or crashes in your next js application code can cause deployment failures or unexpected behavior examine your application logs for any error messages, and address any issues in your code check the container logs by running docker logs your app name to see if there are any errors or exceptions being thrown use a tool like sentry to track and monitor errors in your application server side rendering configuration if your next js application uses server side rendering (ssr), ensure that your ssr setup is correctly configured in your dockerfile and that it starts your application using the right entry point 9 scale your application for more complex projects that require additional resources or horizontal/vertical scaling, consider upgrading your back4app containers plan to handle increased traffic and load 10 sample application for a sample next js application project you can go to https //github com/templates back4app/containers nextjs sample