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:

Install the kraft CLI tool and a container runtime engine, e.g. Docker.
Clone the examples repository and cd into the examples/http-node21/ directory:

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:

# 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:

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

The output shows the instance URL and other details:

[●] 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:

curl https://ancient-haze-sd3wwi0x.fra0.kraft.host

Hello, World!

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

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:

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

spec: v0.6

runtime: node:21

rootfs: ./Dockerfile

cmd: ["/usr/bin/node", "/usr/src/server.js"]

FROM scratch

# Simple Node HTTP server
COPY ./server.js /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:

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:

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

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

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:

Add the package.json file used by npm.
Add framework-specific source files. In our case, this means app/index.js.
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}`)
})

{
  "dependencies": {
    "express": "^4.18.2"
  }
}

spec: v0.6

runtime: node:21

rootfs: ./Dockerfile

cmd: ["/usr/bin/node", "/usr/src/server.js"]

FROM node:21-alpine AS build

WORKDIR /usr/src

COPY . /usr/src/

RUN npm install

FROM scratch

# Distribution configuration
COPY --from=build /etc/os-release /etc/os-release

# Express.js
COPY --from=build /usr/src/app/index.js /usr/src/server.js
COPY --from=build /usr/src/node_modules /usr/src/node_modules

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:

kraft cloud --help

Or visit the CLI Reference.

Run a Node app

Customize your Application

Using npm

Learn More

Using `npm`