Zudoku
Example apps

Next.js HTTP Server

This guide explains how to create and deploy a Next.js app. To run this example, follow these steps:

  1. Install the unikraft CLI. You need a BuildKit builder. The easiest way to get one is via Docker. Alternatively, you can also directly set up and use BuildKit, see the quick start.

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

    TerminalCode
    git clone https://github.com/unikraft-cloud/examples
cd examples/httpserver-node21-nextjs/

Make sure to log into Unikraft Cloud and pick a metro close to you. This guide uses fra (Frankfurt, 🇩🇪):

TerminalCode
unikraft login

When done, invoke the following command to deploy this app on Unikraft Cloud:

TerminalCode
unikraft build . --output <my-org>/httpserver-node21-nextjs:latest
unikraft run --metro fra \
  -m 768M \
  -p 443:3000/tls+http \
  --scale-to-zero policy=on,cooldown-time=1000,stateful=true \
  --image <my-org>/httpserver-node21-nextjs:latest

The output shows the instance address and other details:

TerminalCode
metro:        fra
name:         httpserver-node21-nextjs-bfrq0
uuid:         2adf9664-c4ae-4e0e-99de-c9781282b370
state:        starting
image:        <my-org>/httpserver-node21-nextjs
resources:
  memory:     768MiB
  vcpus:      1
service:
  uuid:       43e93d04-615b-0d81-07af-8506c25b1802
  name:       small-frog-ri8c1vtw
  domains:
  - fqdn:     small-frog-ri8c1vtw.fra.unikraft.app
networks:
- uuid:       e6e3adf9-8512-b678-4dae-6bbf2f4aad17
  private-ip: 10.0.28.2
  mac:        12:b0:2a:aa:d4:82
timestamps:
  created:    just now

In this case, the instance name is httpserver-node21-nextjs-bfrq0 and the address is https://small-frog-ri8c1vtw.fra.unikraft.app. They're different for each run.

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

TerminalCode
curl httpserver-node21-nextjs-bfrq0
Code
<!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 😀.

You can list information about the instance by running:

TerminalCode
unikraft instances list
TerminalCode
METRO  NAME                            STATE    IMAGE                                     ARGS  MEMORY  VCPUS  FQDN                                  CREATED
fra    httpserver-node21-nextjs-bfrq0  running  <my-org>/httpserver-node21-nextjs@sha256        768MiB  1      small-frog-ri8c1vtw.fra.unikraft.app  2 minutes ago

When done, you can remove the instance:

TerminalCode
unikraft instances delete httpserver-node21-nextjs-bfrq0

Customize your app

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

  • Kraftfile: the Unikraft Cloud specification
  • Dockerfile: the Docker-specified app filesystem

Lines in the Kraftfile have the following roles:

  • spec: v0.7: The current Kraftfile specification version is 0.7.

  • runtime: base-compat:latest: The runtime kernel to use is the base compatibility kernel.

  • rootfs: Build the app root filesystem. source: ./Dockerfile means the filesystem is built using the Dockerfile. format: erofs means the filesystem type is EROFS.

  • 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 app:

  • If you only update the implementation in the server.js source file, you don't need to make any other changes.

  • If you want to add extra 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 (see Dockerfile syntax reference). 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's used to install dependencies for Node apps. npm uses a package.json file to list required dependencies (with versions).

The httpserver-expressjs4.18-node21 example in the examples repository details the use of npm to deploy an app using the ExpressJS framework on Unikraft Cloud. Clone the examples repository and cd into the httpserver-expressjs4.18-node21 directory:

TerminalCode
git clone https://github.com/unikraft-cloud/examples
cd examples/httpserver-expressjs4.18-node21/

Run the command below to deploy the app on Unikraft Cloud:

TerminalCode
unikraft build . --output <my-org>/httpserver-expressjs418-node21:latest
unikraft run --metro fra \
  -m 256M \
  -p 443:3000/tls+http \
  --scale-to-zero policy=on,cooldown-time=1000,stateful=true \
  --image <my-org>/httpserver-expressjs418-node21:latest

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 this case, this means app/index.js.

  3. Update the Dockerfile to:

    3.1. COPY the local files.

    3.2. RUN the npm install command to install dependencies.

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

The following lists the files:

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 aren't 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 copy 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 apply to other npm-based apps. See also other Node examples: httpserver-node18-prisma-rest-express and httpserver-node21-nextjs.

Learn more

Use the --help option for detailed information on using Unikraft Cloud:

TerminalCode
unikraft --help

Or visit the CLI Reference.

Last modified on
Neo4jNginx