Skip to content
Unikraft Cloud

Run a Node app

In this guide we create and deploy a simple Node-based HTTP web server. 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/http-node21/ directory:

Terminal window
git clone https://github.com/kraftcloud/examples
cd examples/http-node21/

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

Terminal window
# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra0

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

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

The output shows the instance URL and other details:

Terminal window
[●] Deployed successfully!
 │
 ├────────── name: http-node21-ubl8g
 ├────────── uuid: 6985f8e7-72c2-4726-941c-3c568a83722e
 ├───────── state: running
 ├─────────── url: https://ancient-haze-sd3wwi0x.fra0.kraft.host
 ├───────── image: http-node21@sha256:de174e3703c79a048f0af52344c373296b55f3ca2b96cd29e16c1f014cefd232
 ├───── boot time: 41.65 ms
 ├──────── memory: 256 MiB
 ├─────── service: ancient-haze-sd3wwi0x
 ├── private fqdn: http-node21-ubl8g.internal
 ├──── private ip: 172.16.3.3
 └────────── args: /usr/bin/node /usr/src/server.js

In this case, the instance name is http-node21-ubl8g and the URL is https://ancient-haze-sd3wwi0x.fra0.kraft.host. They are different for each run.

Use curl to query the Unikraft Cloud instance of the Node-based HTTP web server:

Terminal window
curl https://ancient-haze-sd3wwi0x.fra0.kraft.host
Hello, World!

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

Terminal window
kraft cloud instance list
NAME               FQDN                                   STATE    CREATED AT      IMAGE                                   MEMORY   ARGS                              BOOT TIME
http-node21-ubl8g  ancient-haze-sd3wwi0x.fra0.kraft.host  running  50 seconds ago  http-node21@sha256:de174e3703c79a04...  256 MiB  /usr/bin/node /usr/src/server.js  31654us

When done, you can remove the instance:

Terminal window
kraft cloud instance remove http-node21-ubl8g

Customize your Application

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

  • server.js: the actual Node HTTP server
  • Kraftfile: the Unikraft Cloud specification
  • Dockerfile: the Docker-specified application filesystem
const http = require('http'); // Loads the http module


http.createServer((request, response) => {


    // 1. Tell the browser everything is OK (Status code 200), and the data is in plain text
    response.writeHead(200, {
        'Content-Type': 'text/plain'
    });


    // 2. Write the announced text to the body of the page
    response.write('Hello, World!\n');


    // 3. Tell the server that all of the response headers and body have been sent
    response.end();


}).listen(8080); // 4. Tells the server what port to be on

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:

  • FROM scratch: Build the filesystem from the scratch container image, to create a base image.

  • COPY ./server.js /usr/src/server.js: Copy the server implementation file (server.js) in the Docker filesystem (in /usr/src/server.js).

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 Unikraft Cloud. Clone the examples repository and cd into the node21-expressjs directory:

Terminal window
git clone https://github.com/kraftcloud/examples
cd examples/node21-expressjs/

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

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 Unikraft Cloud:

Terminal window
kraft cloud --help

Or visit the CLI Reference.