Skip to content

Run a Next.js app

In this guide we create and deploy a Next.js app. To run this example, follow these steps:

  1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

  2. Clone the examples repository and cd into the examples/node21-nextjs directory:

Terminal window
git clone
cd examples/node21-nextjs/

Make sure to log into KraftCloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

Terminal window
# Set KraftCloud access token
# Set metro to Frankfurt, DE

When done, invoke the following command to deploy the application on KraftCloud:

Terminal window
kraft cloud deploy -p 443:3000 -M 256 .

The output shows the instance URL and other details:

Terminal window
[] Deployed successfully!
────────── name: node21-nextjs-bfrq0
────────── uuid: 2adf9664-c4ae-4e0e-99de-c9781282b370
───────── state: running
─────────── url:
───────── image: node21-nextjs@sha256:ea5b2f145eea9762431ebdea933dd1dfb8427fe23306d2bd7966dd502d6c88f6
───── boot time: 83.60 ms
──────── memory: 256 MiB
service group: small-frog-ri8c1vtw
── private fqdn: node21-nextjs-bfrq0.internal
──── private ip:
────────── args: /usr/bin/node /usr/src/server.js

In this case, the instance name is node21-nextjs-bfrq0 and the URL is They are different for each run.

Use curl to query the KraftCloud instance of the Next.js server:

Terminal window
curl node21-nextjs-bfrq0
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" href="/_next/static/media/c9a5bc6a7c948fb0-s.p.woff2" ...

Or even better, point a browser at it 😀.

At any point in time, you can list information about the instance:

Terminal window
kraft cloud instance list
node21-nextjs-bfrq0 running 1 minute ago node21-nextjs@sha256... 256 MiB /usr/bin/node /usr/src/server.js 83600us

When done, you can remove the instance:

Terminal window
kraft cloud instance remove node21-nextjs-bfrq0

Customize your Application

To customize the application, update the files in the repository, listed below:

  • Kraftfile: the KraftCloud specification
  • Dockerfile: the Docker-specified application filesystem
spec: v0.6
runtime: node:21
rootfs: ./Dockerfile
cmd: ["/usr/bin/node", "/usr/src/server.js"]

Lines in the Kraftfile have the following roles:

  • spec: v0.6: The current Kraftfile specification version is 0.6.

  • runtime: node:21: The Unikraft runtime kernel to use is Node 21.

  • rootfs: ./Dockerfile: Build the application root filesystem using the Dockerfile.

  • cmd: [["/usr/bin/node", "/usr/src/server.js"]]: Use /usr/bin/node /usr/src/server.js as the starting command of the instance.

Lines in the Dockerfile have the following roles:

The following options are available for customizing the application:

  • If only updating the implementation in the server.js source file, no other change is required.

  • If you want to add additional files, you need to copy them into the filesystem using the COPY command in the Dockerfile.

  • If you want to replace server.js with a different source file, update the cmd line in the Kraftfile and replace /usr/src/server.js with the path to your new source file.

  • More extensive changes may require extending the Dockerfile with additional Dockerfile commands. This includes the use of Node frameworks and the use of npm, as shown in the next section.

Using npm

npm is a package manager for Node. It is used to install dependencies for Node applications. npm uses a package.json file to list required dependencies (with versions).

The node21-expressjs example in the examples repository details the use of npm to deploy an application using the ExpressJS framework on KraftCloud. Clone the examples repository and cd into the node21-expressjs directory:

Terminal window
git clone
cd examples/node21-expressjs/

Run the command below to deploy the application on KraftCloud:

Terminal window
kraft cloud deploy -p 443:3000 -M 256 .

Differences from the http-node21 app are also the steps required to create an npm-based app:

  1. Add the package.json file used by npm.

  2. Add framework-specific source files. In our case, this means app/index.js.

  3. Update the Dockerfile to:

    1. COPY the local files.

    2. RUN the npm install command to install dependencies.

    3. COPY of the resulting and required files (node_modules/ and app/index.js) in the application filesystem, using the scratch container.

The files are listed below:

const express = require('express')
const app = express()
const port = 3000
app.get('/', (req, res) => {
res.send('Hello, World!\n')
app.listen(port, () => {
console.log(`Example app listening on port ${port}`)

The package.json file lists the express dependency.

The Kraftfile is the same one used for http-node21.

For Dockerfile newly added lines have the following roles:

  • FROM node:21-alpine AS build: Use the base image of the node:21-alpine container. This provides the npm binary and other Node-related components. Name the current image build.

  • WORKDIR /usr/src: Use /usr/src as working directory. All other commands in the Dockerfile run inside this directory.

  • COPY . /usr/src/: Copy the contents of the local current directory to the Docker filesystem. Note that paths in the .dockerignore file are not copied. This means that package.json and app/index.js are copied.

  • RUN npm install: Install npm components listed in packages.json.

  • COPY --from=build ...: Copy existing files in the new build image in the scratch-based image. /etc/os-release must be copied to provide the distribution information required by node. /usr/src/node_modules are the npm-generated files. /usrc/src/app/index.js is the original ExpressJS source code file.

Similar actions are required for other npm-based applications. See also other Node examples: node18-prisma-rest-express and node21-nextjs.

Learn More

Use the --help option for detailed information on using KraftCloud:

Terminal window
kraft cloud --help

Or visit the CLI Reference.