Skip to main content

Next.js Deployment

Build and host Next.js applications on KloudBean.

Overview​

On KloudBean, you get a complete production-ready stack to build and host high-performance Next.js applications.

You get:

  • Git integration to pull your code on the server
  • SSH access to the server to run commands manually and using ADM tool for quick deployment
  • File Manager access to add, update and manage files with ease

Launching New Next.js Application​

note

If you already have a server and want to launch an app on it, go to Applications → Add Application and add a Next.js app on an existing server.

In this example, we will create a brand new server.

In order to launch your first Next.js app on a new server, navigate to the server provision page:

  1. Select Cloud Provider (your choice)
  2. Select Application (Next.js)
  3. Select Datacenter with nearest location
  4. Add Application Name
  5. Add Server Name
  6. Select Server size depending on needs (for Next.js build minimum recommended size is 2-4GB)

Launch Next.js Application

Click on Launch button and proceed with the payment process (trial or payment).

Once payment is completed, server with Next.js app provisioning will be initiated.

Wait for a while; it will take 5-7 minutes to create your server, configure and deploy a high-performance web stack.

By default, on a new server you will get the following stack versions:

  • Node 20.X
  • NPM 10.X
  • NVM (latest)
  • MariaDB > 10.6 (optional)

Accessing Application Administration​

Once your server is ready, in order to access your Next.js app, select "Apps" from the header menu to go to the Applications page.

On this page, you will see your application in active status.

Application Status

Click on it to navigate to "Application Administration" > "Access" section.

On this section, you will see:

  1. Application default access URL
  2. Server public address to point your custom domain to it

Application Access

Deploying Your Code​

The next step is to deploy your code.

In order to deploy your code, navigate to the "Code Delivery" tab.

Here, on the first tab → "Git deployment":

  1. Click on "Enable Git Integration"
  2. Copy SSH public key and add it to your SCM provider (GitHub, GitLab)

Enable Git Integration

  1. Copy your repo URL and add it here in "Git Repository URL", select branch and "Clone Repository"

Clone Repository

In this example, we're going to deploy an example Next.js app:

https://github.com/one-aalam/next-starter-kit.git

Read the detailed guide on connecting Git.

Once the repo is cloned, the next step is to run the deployment. Click on "Pull & Deploy".

Pull & Deploy

Once you click, it will initiate the build process automatically by doing the following at the backend:

Build Process

  • Take latest repo pull
  • Adding bean.conf to add Next.js basic configuration
  • Installing packages
  • Making build
  • Starting server

Updating bean.conf Script​

Application basic info is mentioned in a file named bean.conf.

In order to create this file, go to the nextjs-src directory and create this file. If the file already exists, update the content.

Using Command Through Shell​

nano /home/admin/hosted-sites/<app_system_user>/nextjs-src/bean.conf

And add the following content:

NODE_VERSION=20.18.0
INSTALL_CMD=npm install
BUILD_CMD=npm run build
APP_DIR=/

Bean Config

Updating/Adding Environment (.env) File​

If you need to add or update the .env file, you can access it using File Manager or optionally using shell.

Navigate to the third tab "FileManager" and click "Launch FileManager" button to open it in a new tab.

Once you are in File Manager, in the nextjs-src directory, you can create a new file .env by clicking on "New file" from the left sidebar.

Give the file name and click "Create".

Create .env File

It will open a new file in the editor. Add your required environment variables. For example:

APP_URL=https://nextjs-232200305.kloudbeansite.com
DB_HOST=localhost
DB_NAME=kb_w594wx426b
DB_USERNAME=kb_w594wx426b
DB_PASSWORD=31vYF9Dc65gHbV742m

In order to get database access credentials, read the detailed guide on Viewing Database Credentials.

Environment Variables

Once updated, click on the "Save" icon on the top right corner of the editor, and it will be saved.

Viewing Build Logs​

If you see your build failed or you need to see build and installation logs, click on your current build and a prompt will open to view the logs.

View Build Logs

Once your application is started, you can access it from the access URL:

"Application Administration" → Access → Access URL

If you are seeing 503, that means your application is not up and has some errors.

In order to view application logs:

  • You can view logs using File Manager
  • Or by SSH into the server

Go to directory: /home/admin/hosted-sites/<app_system_user>/app-logs

note

Important: It is important to check your application logs if your site is responding with a 503 gateway error. It shows that the application is not running.

In this directory, application logs are being added in the following log files:

  • app.info.log → information logs
  • app.error.log → error logs

You can open these files using File Manager to view the errors.

Deployment Using ADM Tool (Application Deployment Manager)​

Application Deployment Manager (ADM) is one of KloudBean's features that enables you to deploy your app quickly by just executing one command. It supports all Node.js and Python-based applications.

In order to perform deployment using the ADM tool, you have to access your server using shell.

Read the detailed guide on how to SSH server on KloudBean.

Once you are connected to the server, run the following ADM command:

sudo adm

or

sudo adm <app_system_user>

→ to directly execute for the required application.

ADM Command

If you run this command without app_system_user, then you will have to select the app by providing its number in the prompt and click hit enter.

It will start the deployment process with the logs and progress details on the shell screen.

ADM Deployment

note

Information: While executing deployment through ADM, you will see the port as well to get to know on which port the app is running.

Handling Build Errors​

If you are seeing the build has failed, you can see build logs for the error details.

Viewing Application Logs​

For app logs, go to the app-logs directory:

tail -100 /home/admin/hosted-sites/<app_system_user>/app-logs/app.error.log

While executing ADM, you might see the app failed. Carefully watch the error and try to fix it.

Common Next.js Build Errors​

1. OpenSSL Digital Envelope Error​

Error:

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:101:19)
    at Object.createHash (node:crypto:139:10)

Solution: This error occurs when using Node.js 17+ with older versions of Next.js or webpack. You have several options:

  1. Use Node.js 16 (recommended for older Next.js versions):

    • Update NODE_VERSION in bean.conf to 16.20.2 or similar

  2. Upgrade Next.js (recommended):

    • Update to Next.js 13+ which is compatible with Node.js 20
    • Update your package.json: 
      {
        "dependencies": {
          "next": "^13.0.0"
        }
      }

  3. Use legacy OpenSSL provider (temporary workaround):

    • Add to your package.json scripts: 
      {
        "scripts": {
          "build": "NODE_OPTIONS=--openssl-legacy-provider next build"
        }
      }

2. Module Not Found Errors​

Error: Module not found: Can't resolve 'xxx'

Solution:

  • Ensure all dependencies are listed in package.json
  • Run npm install to install missing packages
  • Check for typos in import statements
  • Verify the package is compatible with your Next.js version

3. Build Timeout Errors​

Error: Build process times out

Solution:

  • Increase build timeout in bean.conf if available
  • Optimize your build process
  • Remove unnecessary dependencies
  • Check for circular dependencies

4. Memory Errors During Build​

Error: JavaScript heap out of memory

Solution:

  • Increase Node.js memory limit in bean.conf: 
    NODE_OPTIONS=--max-old-space-size=4096
  • Optimize your build configuration
  • Split large components or pages

Once the error is fixed, then run the build again using "Pull & Deploy" or using the ADM tool from shell.

Deploying Only Frontend Next.js App​

If you want to deploy a Next.js app as a static frontend-only application (without server-side rendering), you need to make the following changes:

1. Update next.config.js​

Add the static export configuration:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true, // Required for static export
  },
  trailingSlash: true,
}

module.exports = nextConfig

2. Update package.json​

Modify your build and start scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "export": "next build && next export"
  }
}
note

Important: When using static export:

  • API routes (pages/api/) are not available
  • Server-side rendering features are disabled
  • Dynamic routes require getStaticPaths
  • Images must use unoptimized: true or external image domains

3. Update bean.conf​

For static export, you can use:

NODE_VERSION=20.18.0
INSTALL_CMD=npm install
BUILD_CMD=npm run build
APP_DIR=/out

The APP_DIR should point to the out directory where Next.js exports the static files.

Next Steps​