Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions content/guides/catalog-behind-the-scenes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ It is aimed for those more technically inclined who would be interested in under
Similar to the [guide on using the application catalog](/guides/using-the-app-catalog), we will use two applications:

- [the `nginx/1.25` application](https://github.com/unikraft/catalog/tree/main/library/nginx/1.25)
- [the `http-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/http-go1.21)
- [the `httpserver-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/httpserver-go1.21)

## NGINX

Expand All @@ -23,17 +23,16 @@ The build phase creates the output kernel, and the run phase launches a Unikraft
The kernel is a join of the actual Unikraft kernel and the application filesystem, packed as an initial ramdisk.
We call the packed initial ramdisk the **embedded initial ramdisk** or **embedded initrd**.

### Configuration
### NGINX configuration

The build and run configuration is part of the [`Kraftfile`](https://github.com/unikraft/catalog/blob/main/library/nginx/1.25/Kraftfile).

The `Kraftfile` defines the:

- resulting image name: `nginx`
- the command line to start the application: `/usr/bin/nginx`
- path to the template `app-elfloader`
- paths and versions of repositories (`unikraft`, `lwip`, `libelf`)
- configuration options: i.e. the `CONFIG_...` option enables the emdedded initrd build
- configuration options: the `CONFIG_...` option enables the embedded initrd build
- build and run targets: currently only x86_64-based builds are available, and only KVM-based builds, using QEMU or Firecracker
- root filesystem used to build the (embedded) initrd

Expand Down Expand Up @@ -109,7 +108,8 @@ The resulting embedded kernel image is `.unikraft/build/nginx_qemu-x86_64`:
```bash
$ ls -lh .unikraft/build/nginx_qemu-x86_64
```
```

```text
-rwxr-xr-x 2 razvand docker 15M Jan 2 21:23 .unikraft/build/nginx_qemu-x86_64
```

Expand Down Expand Up @@ -170,14 +170,14 @@ To close the running QEMU instance, use `Ctrl+a x` in the QEMU console.

## HTTP Go Server

For the [`http-go1.21` bincompat example](https://github.com/unikraft/catalog/tree/main/examples/http-go1.21), there is no build phase, only a run phase.
For the [`httpserver-go1.21` bincompat example](https://github.com/unikraft/catalog/tree/main/examples/httpserver-go1.21), there is no build phase, only a run phase.
The example is using a prebuilt kernel image.
The prebuilt [`base` kernel image](https://github.com/unikraft/catalog/tree/main/library/base) is pulled from the registry, from `unikraft.org/base`.
This happens during the run phase.

### Configuration
### Run configuration

The run configuration is part of the [`Kraftfile`](https://github.com/unikraft/catalog/blob/main/examples/http-go1.21/Kraftfile):
The run configuration is part of the [`Kraftfile`](https://github.com/unikraft/catalog/blob/main/examples/httpserver-go1.21/Kraftfile):

```yaml
spec: v0.6
Expand All @@ -191,7 +191,7 @@ cmd: ["/server"]

The `Kraftfile` defines:

- the runtime image to use, containing the kernel: `unikraft.org/base:latest' (it can be summarized as just `base:latest`)
- the runtime image to use, containing the kernel: `unikraft.org/base:latest` (it can be summarized as just `base:latest`)
- the root filesystem used, defined in a `Dockerfile`
- the command line to start the application: `/server`
- the available run targets: currently only x86_64-based builds are available, and only KVM-based builds, using QEMU or Firecracker
Expand Down Expand Up @@ -224,7 +224,7 @@ COPY --from=build /lib64/ld-linux-x86-64.so.2 /lib64/

The Dockerfile is being interpreted via [BuildKit](https://docs.docker.com/build/buildkit/), hence the need to set up the BuildKit container.

### Run Phase
### HTTP Go Server run phase

The run command requires the `BuildKit` container to be configured beforehand:

Expand Down Expand Up @@ -253,7 +253,8 @@ The resulting initrd image is `.unikraft/build/initramfs.cpio`.
```bash
$ ls -lh .unikraft/build/initramfs.cpio
```
```

```text
-rw-r--r-- 1 root root 8.9M Jan 4 18:16 .unikraft/build/initramfs-x86_64.cpio
```

Expand All @@ -262,7 +263,8 @@ To view the contents of the root filesystem you can use `cpio`:
```bash
$ cpio -itv < .unikraft/build/initramfs.cpio
```
```

```text
d--------- 0 root root 0 Jan 1 1970 /lib
d--------- 0 root root 0 Jan 1 1970 /lib/x86_64-linux-gnu
-rwxr-xr-x 1 root root 1922136 Sep 30 11:31 /lib/x86_64-linux-gnu/libc.so.6
Expand Down
7 changes: 4 additions & 3 deletions content/guides/catalog-using-firecracker.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ sudo cp release-v1.4.0-x86_64/firecracker-v1.4.0-x86_64 /usr/local/bin/firecrack
Similar to the ["Application Catalog: Behind the Scenes" guide](/guides/catalog-behind-the-scenes), we will use two applications:

- [the `nginx/1.25` application](https://github.com/unikraft/catalog/tree/main/library/nginx/1.25)
- [the `http-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/http-go1.21)
- [the `httpserver-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/httpserver-go1.21)

## NGINX

Expand Down Expand Up @@ -143,7 +143,7 @@ Use the steps below to build and run the HTTP Go server as a binary-compatible a
1. Enter the HTTP Go server example directory:

```bash
cd catalog/examples/http-go1.21/
cd catalog/examples/httpserver-go1.21/
```

1. Pull the unikernel `base` image for the Firecracker (`fc`) platform:
Expand All @@ -169,7 +169,8 @@ Use the steps below to build and run the HTTP Go server as a binary-compatible a
```bash
$ ls -lh .unikraft/build/initramfs-x86_64.cpio
```
```

```text
-rw-r--r-- 1 razvand razvand 9.7M Jan 26 18:50 .unikraft/build/initramfs-x86_64.cpio
```

Expand Down
27 changes: 16 additions & 11 deletions content/guides/using-the-app-catalog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ You can list the applications in the registry by using:
```bash
kraft pkg ls --apps --all --update
```
```

```text
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
Expand Down Expand Up @@ -57,7 +58,7 @@ 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:

```
```text
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/helloworld
o. .o _ _ __ _
Expand All @@ -84,7 +85,8 @@ Similarly, we can pull and run Nginx:
```bash
kraft run -W unikraft.org/nginx:1.15
```
```

```text
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/nginx
o. .o _ _ __ _
Expand All @@ -101,7 +103,8 @@ In order to connect to it, we need to pass a port mapping, similar to [`docker`
```bash
kraft run -W -p 8080:80 unikraft.org/nginx:1.15
```
```

```text
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/nginx
Powered by
Expand All @@ -113,7 +116,6 @@ oOo oOO| | | | | (| | | (_) | _) :_
Telesto 0.16.1~b1fa7c5
```


<Info>
You can use Nginx version 1.25 instead of version 1.15 by appending `:1.25` to the `kraft run` command.
For example: `kraft run -W unikraft.org/nginx:1.25`
Expand All @@ -125,7 +127,8 @@ Query the server to get the index page:
```bash
curl localhost:8080
```
```

```text
<!DOCTYPE html>
<html>
<head>
Expand All @@ -148,7 +151,8 @@ First create a bridge interface, as `root` (prefix with `sudo` if required):
```bash
sudo kraft run --network virbr0 unikraft.org/nginx:1.15
```
```

```text
i using arch=x86_64 plat=qemu
[+] pulling unikraft.org/nginx
en1: Interface is up
Expand All @@ -166,7 +170,8 @@ The IP address used is typically the first available address (`172.44.0.2`, if t
```bash
curl 172.44.0.2
```
```

```text
<!DOCTYPE html>
<html>
<head>
Expand Down Expand Up @@ -195,7 +200,7 @@ The end-user appplications are built, packaged and published periodically in the
We present the steps to building application and running them locally for:

- [the `nginx/1.25` application](https://github.com/unikraft/catalog/tree/main/library/nginx/1.25)
- [the `http-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/http-go1.21)
- [the `httpserver-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/httpserver-go1.21)

Both are running in binary-compatibility mode.

Expand Down Expand Up @@ -278,13 +283,13 @@ This is generally the case for end-user applications, located in the [`library/`
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](https://github.com/unikraft/catalog/tree/main/examples).
The application / example is then passed via an initial ramdisk.
One such example is the [`http-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/http-go1.21).
One such example is the [`httpserver-go1.21` example](https://github.com/unikraft/catalog/tree/main/examples/httpserver-go1.21).
Follow the steps below to build and run the example:

1. Enter the example directory:

```bash
cd catalog/examples/http-go1.21
cd catalog/examples/httpserver-go1.21
```

1. Run:
Expand Down
Loading