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 andcd
into theexamples/http-node21/
directory:
git clone https://github.com/kraftcloud/examplescd 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 tokenexport UKC_TOKEN=token# Set metro to Frankfurt, DEexport 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 TIMEhttp-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 serverKraftfile
: the Unikraft Cloud specificationDockerfile
: 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 serverCOPY ./server.js /usr/src/server.js
Lines in the Kraftfile
have the following roles:
-
spec: v0.6
: The currentKraftfile
specification version is0.6
. -
runtime: node:21
: The Unikraft runtime kernel to use is Node 21. -
rootfs: ./Dockerfile
: Build the application root filesystem using theDockerfile
. -
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 thescratch
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 theDockerfile
. -
If you want to replace
server.js
with a different source file, update thecmd
line in theKraftfile
and replace/usr/src/server.js
with the path to your new source file. -
More extensive changes may require extending the
Dockerfile
with additionalDockerfile
commands. This includes the use of Node frameworks and the use ofnpm
, 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/examplescd 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 bynpm
. -
Add framework-specific source files. In our case, this means
app/index.js
. -
Update the
Dockerfile
to:-
COPY
the local files. -
RUN
thenpm install
command to install dependencies. -
COPY
of the resulting and required files (node_modules/
andapp/index.js
) in the application filesystem, using thescratch
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 configurationCOPY --from=build /etc/os-release /etc/os-release
# Express.jsCOPY --from=build /usr/src/app/index.js /usr/src/server.jsCOPY --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 thenode:21-alpine
container. This provides thenpm
binary and other Node-related components. Name the current imagebuild
. -
WORKDIR /usr/src
: Use/usr/src
as working directory. All other commands in theDockerfile
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 thatpackage.json
andapp/index.js
are copied. -
RUN npm install
: Installnpm
components listed inpackages.json
. -
COPY --from=build ...
: Copy existing files in the newbuild
image in thescratch
-based image./etc/os-release
must be copied to provide the distribution information required by node./usr/src/node_modules
are thenpm
-generated files./usrc/src/app/index.js
is the originalExpressJS
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.