DocsReleasesCommunityGuidesBlog

Using the Application Catalog

This guide presents the Unikraft application catalog and how to use it: build and run applications. It is meant for anyone interested in using Unikraft and benefiting from technical advantages of unikernels.

The Unikraft application catalog is a collection of applications and examples that are built and packaged to run with Unikraft. The application packages are stored in the Unikraft Application Registry, typically identified by a name similar to those used by DockerHub: unikraft.org/node:18, unikraft.org/python:3.10.

The catalog stores both native builds and binary-compatible builds of Unikraft applications. As a user it shouldn't matter to you. KraftKit is used to provide the same build and run interface for both native and binary-compatible apps.

Running Applications from the Registry#

You can list the applications in the registry by using:

$ kraft pkg ls --apps --all --update
TYPE NAME VERSION FORMAT MANIFEST INDEX PLAT
app unikraft.org/base latest oci 18cd70e af5c5ed qemu/x86_64
app unikraft.org/base latest oci ac5efa1 af5c5ed fc/x86_64
app unikraft.org/helloworld latest oci 8f6c8ff 01f213a fc/x86_64
app unikraft.org/helloworld latest oci 6686724 01f213a xen/x86_64
app unikraft.org/helloworld latest oci 225f853 01f213a linuxu/arm64
app unikraft.org/helloworld latest oci 45782c1 01f213a qemu/arm64
app unikraft.org/helloworld latest oci 603e401 01f213a qemu/x86_64
app unikraft.org/helloworld latest oci c156b11 01f213a linuxu/x86_64
app unikraft.org/lua 5.4 oci 5aa7cae 22b92ef qemu/x86_64
app unikraft.org/lua 5.4 oci 4910f7f 22b92ef fc/x86_64
app unikraft.org/lua 5.4 oci bb9f1bb 22b92ef fc/arm64
app unikraft.org/lua 5.4 oci a0e36f4 22b92ef qemu/arm64
app unikraft.org/nginx 1.15 oci 11012dd 05c88f3 qemu/arm64
app unikraft.org/nginx 1.15 oci 789628a 05c88f3 qemu/x86_64
app unikraft.org/nginx 1.15 oci c6934f4 05c88f3 fc/x86_64
app unikraft.org/nginx 1.15 oci 2c70788 05c88f3 fc/arm64
app unikraft.org/python 3.10 oci ecb5863 1f0939e fc/x86_64
app unikraft.org/python 3.10 oci 2d74e1b 1f0939e qemu/x86_64
app unikraft.org/redis 7.0 oci ee39581 1661b08 qemu/arm64
app unikraft.org/redis 7.0 oci a87f72f 1661b08 qemu/x86_64
app unikraft.org/redis 7.0 oci 9c726bc 1661b08 fc/arm64
app unikraft.org/redis 7.0 oci 77d88f3 1661b08 fc/x86_64

The base entry is a meta-application that is being used in binary-compatibility mode to run other applications and examples. The other entries may be binary-compatible or native builds.

To pull and run helloworld, for example, use:

kraft run -W unikraft.org/helloworld

This will default to the x86_64 architecture and to the qemu platform. It will pull and run run the application from the registry:

i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/helloworld
o. .o _ _ __ _
Oo Oo ___ (_) | __ __ __ _ ' _) :_
oO oO ' _ `| | |/ / _)' _` | |_| _)
oOo oOO| | | | | (| | | (_) | _) :_
OoOoO ._, ._:_:_,\_._, .__,_:_, \___)
Telesto 0.16.1~b1fa7c5
Hello from Unikraft!
This message shows that your installation appears to be working correctly.
For more examples and ideas, visit: https://unikraft.org/docs/

The -W option for kraft run is used to disable hardware virtualization (KVM). This is useful if you are running Unikraft applications inside a virtual machine. If you are running natively (for maximum performance), and if you likely have hardware virtualization support, you can remove the -W option.

Similarly, we can pull and run Nginx:

kraft run -W unikraft.org/nginx
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/nginx
o. .o _ _ __ _
Oo Oo ___ (_) | __ __ __ _ ' _) :_
oO oO ' _ `| | |/ / _)' _` | |_| _)
oOo oOO| | | | | (| | | (_) | _) :_
OoOoO ._, ._:_:_,\_._, .__,_:_, \___)
Telesto 0.16.1~b1fa7c5

Note that the Nginx server starts but waits for a connection. In order to connect to it, we need to pass a port mapping, similar to docker commands:

kraft run -W -p 8080:80 unikraft.org/nginx
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/nginx
Powered by
o. .o _ _ __ _
Oo Oo ___ (_) | __ __ __ _ ' _) :_
oO oO ' _ `| | |/ / _)' _` | |_| _)
oOo oOO| | | | | (| | | (_) | _) :_
OoOoO ._, ._:_:_,\_._, .__,_:_, \___)
Telesto 0.16.1~b1fa7c5

With the command above we mapped the local port 8080 to the internal Nginx Unikraft port 80: Query the server to get the index page:

curl localhost:8080
<!DOCTYPE html>
<html>
<head>
<title>Hello, world!</title>
</head>
<body>
<h1>Hello from Unikraft!</h1>
<p>This message shows that your installation appears to be working correctly.</p>
<p></p>For more examples and ideas, visit <a href="https://unikraft.org/docs/">Unikraft's Documentation</a>.</p>
</body>
</html>

This a local port mapping, running on localhost. For an IP-based network connection, you can use a bridged interface. First create a bridge interface, as root (prefix with sudo if required):

sudo kraft run --network bridge:virbr0 unikraft.org/nginx
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/nginx
en1: Interface is up
Powered by
o. .o _ _ __ _
Oo Oo ___ (_) | __ __ __ _ ' _) :_
oO oO ' _ `| | |/ / _)' _` | |_| _)
oOo oOO| | | | | (| | | (_) | _) :_
OoOoO ._, ._:_:_,\_._, .__,_:_, \___)
Telesto 0.16.1~b1fa7c5

The IP address used is typically the first available address (172.44.0.2, if that doesn't work try 172.44.0.3) so we query the server using that address:

curl 172.44.0.2
<!DOCTYPE html>
<html>
<head>
<title>Hello, world!</title>
</head>
<body>
<h1>Hello from Unikraft!</h1>
<p>This message shows that your installation appears to be working correctly.</p>
<p></p>For more examples and ideas, visit <a href="https://unikraft.org/docs/">Unikraft's Documentation</a>.</p>
</body>
</html>

The Application Catalog Repository#

Application in the registry are built and packaged using the recipes and source code files in the catalog repository. The catalog repository contains two types of entries:

The end-user appplications are built, packaged and published periodically in the registry.

We present the steps to building application and running them locally for:

Both are running in binary-compatibility mode.

For building and running binary-compatible applications, KraftKit and Docker are required.

NGINX#

Follow the steps below to build and run the NGINX binary-compatible application:

  1. Set up the BuildKit container, if not already running:

    docker run -d --name buildkitd --privileged moby/buildkit:latest
    export KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd
  2. Clone the catalog repository:

    git clone https://github.com/unikraft/catalog
  3. Enter the application directory:

    cd catalog/library/nginx/1.25
  4. Build the application:

    kraft build --plat qemu --arch x86_64
  5. Run the application with 8080:80 port mapping.:

    kraft run -W -p 8080:80 .
  6. Query the unikernel instance:

    curl http://localhost:8080

If, instead of port mapping, you want to use bridge networking, follow the steps:

  1. As root (prefix with sudo if required), create a network interface bridge:

    kraft net create -n 172.44.0.1/24 virbr0
  2. Run as root (prefix with sudo if required):

    kraft run --network bridge:virbr0 .
  3. Query the unikernel instance:

    curl http://172.44.0.2

To close the running kraft instance, remove the corresponding kraft process. Run, as root (prefix with sudo if required):

kraft rm --all

HTTP Go Server#

The NGINX build / run uses a feature called "embedded initrd", that embeds and initial ramdisk with the kernel. The initial ramdisk contains with the NGINX application binary and depending libraries. This is generally the case for end-user applications, located in the library/ directory.

Another approach is to use a base image that is not embedding an actual application. This is the case for examples, located in the examples/ directory. The application / example is then passed via an initial ramdisk. One such example is the http-go1.21 example. Follow the steps below to build and run the example:

  1. Enter the example directory:

    cd catalog/examples/http-go1.21
  2. Run:

    kraft run -W -p 8080:8080 .
  3. Query the unikernel instance:

    curl http://localhost:8080

If, instead of port mapping, you want to use bridge networking, follow the steps:

  1. As root (prefix with sudo if required), create a network interface bridge:

    kraft net create -n 172.44.0.1/24 virbr0
  2. Run as root (prefix with sudo if required):

    sudo KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd kraft run --network bridge:virbr0 .
  3. Query the unikernel instance:

    curl http://172.44.0.2:8080

To close the running kraft instance, remove the corresponding kraft process. Run, as root (prefix with sudo if required):

kraft rm --all
Edit this page on GitHub

Connect with the community

Feel free to ask questions, report issues, and meet new people.

Join us on Discord!
®

Getting Started

What is a unikernel?Install CLI companion toolUnikraft InternalsRoadmap

© 2024  The Unikraft Authors. All rights reserved. Documentation distributed under CC BY-NC 4.0.