Unikraft

https://unikraft.org/docs
Admin
Unikraft is a fast, secure, and open-source Unikernel Development Kit for building minimal,...
Tokens:156,898
Snippets:1,615
Trust Score:8.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Complex Unikraft Configuration Example (YAML)

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

A comprehensive example combining source location, version, and KConfig options to precisely define the Unikraft core configuration.

```yaml
unikraft:
  source: https://github.com/unikraft/unikraft.git
  version: stable
  kconfig:
    CONFIG_EXAMPLE: "y"
spec: v0.6
name: helloworld
```

--------------------------------

### Bring Up Unikraft Compose Project

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Creates, builds, and starts all services defined in a Unikraft Compose file. A convenient command to get a system running.

```Shell
kraft compose up
```

--------------------------------

### Install Dependencies and Run Dev Server (Docker)

Source: https://unikraft.org/docs/contributing/docs

Installs project dependencies using Yarn and starts the development server for the Unikraft documentation. These commands are intended to be run inside the Docker container.

```shell
yarn install
yarn run dev

```

--------------------------------

### Start Unikraft Cloud Compose Services

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/compose/start

Starts services defined in a Unikraft Cloud Compose project. This command can start all services or specific components. It accepts options to wait for instances to start and inherited options for environment files, compose files, metro locations, and access tokens.

```bash
# Start all services in a Unikraft Cloud Compose project.
$ kraft cloud compose start

# Start the nginx service
$ kraft cloud compose start nginx
```

--------------------------------

### Install Unikraft CLI

Source: https://unikraft.org/docs/cli

Installs the `kraft` binary and necessary dependencies on your host system. The installer automatically detects your OS and suggests the most appropriate installation method. It requires `curl` to download the installation script.

```shell
curl --proto '=https' --tlsv1.2 -sSf https://get.kraftkit.sh | sh
```

--------------------------------

### kraft cloud instance start

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/instance/start

This command allows you to start one or more instances on KraftCloud. You can specify instances by their UUID or name, or choose to start all instances.

```APIDOC
## POST /kraft/cloud/instance/start

### Description
Start an instance on KraftCloud from a stopped instance.

### Method
POST

### Endpoint
/kraft/cloud/instance/start

### Parameters
#### Query Parameters
- **uuid** (string) - Required - The UUID or name of the instance(s) to start.
- **all** (boolean) - Optional - If true, starts all instances.
- **wait** (duration) - Optional - Timeout to wait for the instance to start (e.g., "500ms", "2s", "1m").
- **metro** (string) - Optional - Unikraft Cloud metro location.
- **token** (string) - Optional - Unikraft Cloud access token.

### Request Body
None

### Request Example
```bash
# Start an instance by UUID
$ kraft cloud instance start 77d0316a-fbbe-488d-8618-5bf7a612477a

# Start an instance by name
$ kraft cloud instance start my-instance-431342

# Start multiple instances
$ kraft cloud instance start my-instance-431342 my-instance-other-2313

# Start all instances with a wait timeout
$ kraft cloud instance start --all --wait 1m
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the instance(s) have been started.

#### Response Example
```json
{
  "message": "Instance(s) started successfully."
}
```

#### Error Handling
- **400 Bad Request**: If the instance UUID/name is invalid or the instance is not in a stoppable state.
- **401 Unauthorized**: If the access token is invalid or missing.
- **404 Not Found**: If the specified instance does not exist.
- **500 Internal Server Error**: If there is a server-side error during the operation.
```

--------------------------------

### Example: Create Unikraft Cloud Compose Deployment

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/compose/create

An example demonstrating how to initiate a deployment using the `kraft cloud compose create` command without any specific flags or components.

```bash
$ kraft cloud compose create

```

--------------------------------

### kraft cloud compose start

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/compose/start

Starts services in a Unikraft Cloud Compose project deployment. You can start all services or specify individual components.

```APIDOC
## POST /cloud/compose/start

### Description
Starts services in a Unikraft Cloud Compose project deployment. This command allows for starting all services within a project or targeting specific components.

### Method
POST

### Endpoint
/cloud/compose/start

### Parameters
#### Query Parameters
- **component** (string) - Optional - The name of the specific service component to start.
- **wait** (duration) - Optional - Timeout duration to wait for the instance to start (e.g., 'ms', 's', 'm', 'h').
- **env-file** (string) - Optional - Path to the environment file.
- **file** (string) - Optional - Path to the Compose file.
- **metro** (string) - Optional - The Unikraft Cloud metro location.
- **token** (string) - Optional - Unikraft Cloud access token.

### Request Example
```json
{
  "command": "kraft cloud compose start",
  "arguments": [
    "nginx"
  ],
  "options": {
    "wait": "1m",
    "metro": "us-east-1"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the services have started or are starting.

#### Response Example
```json
{
  "message": "Services started successfully."
}
```

### See Also
- `kraft cloud compose`: Manage Compose deployments on Unikraft Cloud
```

--------------------------------

### Start Unikraft Cloud Compose Project

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Starts services defined in a Unikraft Cloud Compose file on the Unikraft Cloud. Brings deployed services online.

```Shell
kraft cloud compose start
```

--------------------------------

### Start Unikraft Cloud Instance

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/instance/start

Command to start a stopped Unikraft instance on KraftCloud. It can start instances by their UUID or name, and supports starting multiple instances simultaneously. Options include waiting for the instance to start with a specified timeout.

```bash
# Start an instance by UUID
$ kraft cloud instance start 77d0316a-fbbe-488d-8618-5bf7a612477a

# Start an instance by name
$ kraft cloud instance start my-instance-431342

# Start multiple instances
$ kraft cloud instance start my-instance-431342 my-instance-other-2313

```

--------------------------------

### Python Flask Web Server Example

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

A simple Python Flask web server application. This code defines a basic Flask app with a single route that returns 'Hello, World!'. It's intended as an example for the Unikraft catalog and requires the 'flask' package.

```python
from flask import Flask
app = Flask(__name__)


@app.route('/')
def hello():
    return "Hello, World!\n"


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

```

```text
flask

```

--------------------------------

### Install Unikraft 'kraft' Tool

Source: https://unikraft.org/docs/getting-started

This snippet shows the command to install the 'kraft' tool, which is essential for managing Unikraft unikernels throughout their lifecycle. It uses curl to download and execute the installation script.

```shell
curl -sSfL https://get.kraftkit.sh | sh
```

--------------------------------

### Start Unikraft Compose Project

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Starts or restarts all unikernels defined in a Unikraft Compose file. Brings the system online.

```Shell
kraft compose start
```

--------------------------------

### kraft compose start

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img

The `kraft compose start` command starts the containers of a compose project. This command begins the execution of the containers.

```APIDOC
## kraft compose start

### Description
Starts the containers of a compose project.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Query Local HTTP Server (Shell)

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

Sends an HTTP GET request to the local server running on port 8080 to verify its functionality. This is typically done after starting the server.

```shell
curl localhost:8080
```

--------------------------------

### Local Runtime Commands

Source: https://unikraft.org/docs/cli/reference/kraft/compose/build

Manage local Unikraft instances, including starting, stopping, and viewing logs.

```APIDOC
## Local Runtime Commands

### Description
Commands for managing local Unikraft runtime instances.

### Commands
- **`kraft logs`**: View logs of a running instance.
- **`kraft pause`**: Pause a running instance.
- **`kraft ps`**: List running instances.
- **`kraft remove`**: Remove a stopped instance.
- **`kraft run`**: Run a new instance.
- **`kraft start`**: Start a stopped instance.
- **`kraft stop`**: Stop a running instance.
```

--------------------------------

### Start a Machine using `kraft start`

Source: https://unikraft.org/docs/cli/reference/kraft/start

This command starts one or more specified machines. It supports options for starting all machines, running in the background, setting the platform driver, and automatically removing the unikernel upon shutdown. The command requires machine names as arguments.

```bash
# Start a machine
$ kraft start my-machine
```

--------------------------------

### Example: Running Textlint on a Specific File

Source: https://unikraft.org/docs/contributing/docs

Shows an example of running textlint on a specific Markdown file (code-of-conduct.mdx) using its configuration file. This command will report any linting errors found in the file according to the configured rules.

```bash
npx textlint --config .github/workflows/.textlintrc content/docs/contributing/code-of-conduct.mdx
```

--------------------------------

### Build and Install runu from Source (Shell)

Source: https://unikraft.org/docs/getting-started/integrations/container-runtimes

Clones the KraftKit repository, builds the runu binary using make, and installs it into the system's PATH. This method is useful for development or custom builds.

```shell
git clone https://github.com/unikraft/kraftkit.git
make runu
# PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
sudo install runu /usr/local/bin/
```

--------------------------------

### Direct Unikraft Core Makefile Invocation Example

Source: https://unikraft.org/docs/internals/build-system

An example demonstrating how to directly invoke the Unikraft core Makefile, specifying paths to libraries. This achieves the same result as the wrapper Makefile example.

```bash
$ make -C workdir/unikraft A=. L=workdir/libs/lib1:workdir/libs/lib2:workdir/libs/libN
```

--------------------------------

### Install Redis Tools on Debian/Ubuntu

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command installs the `redis-tools` package, which includes the `redis-cli` utility. This tool is necessary for interacting with a Redis server. It requires root privileges or `sudo`.

```bash
apt install redis-tools
```

--------------------------------

### Miscellaneous Commands

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/service

Utility commands for logging in, checking versions, and getting help.

```APIDOC
## Miscellaneous Commands

### Description
Utility commands for interacting with the Unikraft CLI and its services.

### Commands
- `kraft login`: Logs the user into KraftCloud.
- `kraft version`: Displays the installed Unikraft CLI version.
- `kraft completion`: Generates shell completion scripts.
- `kraft help`: Displays help information for commands.
```

--------------------------------

### Set up Windows Subsystem for Linux (WSL2) for KraftKit

Source: https://unikraft.org/docs/cli/install

Installs and configures Windows Subsystem for Linux 2 (WSL2) with a Debian distribution to run KraftKit. This involves installing WSL2, shutting down and restarting the WSL instance, and configuring nested virtualization.

```bash
wsl --install -d debian
```

```bash
wsl.exe --shutdown
```

```powershell
[wsl2]
nestedVirtualization=true

[boot]
command = "/bin/bash -c 'chown -v root:kvm /dev/kvm && chmod 660 /dev/kvm'"
```

```bash
sudo usermod -a -G kvm ${USER}
```

--------------------------------

### Start Cloud Instance

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Starts a stopped Unikraft Cloud instance. Resumes the execution of a unikernel in the cloud.

```Shell
kraft cloud instance start
```

--------------------------------

### Create Docker Container Instance (Shell)

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

Creates a Docker container instance named 'minimal-http-tokio-cont' from the 'minimal-http-tokio' image, preparing it for filesystem export. This command does not start the container.

```shell
docker create --name minimal-http-tokio-cont minimal-http-tokio /server
```

--------------------------------

### kraft start

Source: https://unikraft.org/docs/cli/reference/kraft/start

Starts one or more machines (unikernels) on the local system.

```APIDOC
## kraft start

### Description
Start one or more machines (unikernels) on the local system.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### Path Parameters
- **MACHINE** (string) - Required - The name(s) of the machine(s) to start.

#### Query Parameters
None

#### Flags
- **--all** (boolean) - Optional - Start all machines.
- **-d, --detach** (boolean) - Optional - Run in background.
- **-h, --help** (boolean) - Optional - Display help information for the start command.
- **--no-prefix** (boolean) - Optional - When starting multiple machines, do not prefix each log line with the name.
- **-p, --plat string** (string) - Optional - Set the platform virtual machine monitor driver. Set to 'auto' to detect the guest's platform and 'host' to use the host platform. (default "auto")
- **--rm** (boolean) - Optional - Automatically remove the unikernel when it shuts down.

### Request Example
```bash
# Start a machine
$ kraft start my-machine

# Start all machines in detached mode
$ kraft start --all -d
```

### Response
#### Success Response (0)
- Output indicating the status of the started machine(s).

#### Response Example
```
[INFO] Starting machine my-machine...
```

### See Also
- [`kraft`](/docs/cli/kraft)
- [`kraft stop`](/docs/cli/kraft-stop)
- [`kraft ps`](/docs/cli/kraft-ps)
```

--------------------------------

### Kraftfile Specification Attribute Example

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

Shows an alternative way to specify the Kraftfile version using the 'specification' attribute, which is supported for legacy reasons. It also demonstrates the 'spec' attribute.

```yaml
specification: v0.6
```

--------------------------------

### QEMU initrd flag for external initramfs

Source: https://unikraft.org/docs/cli/filesystem

Example of how to specify the path to an external initramfs archive file when launching a virtual machine using QEMU.

```bash
qemu-system-x86_64 \ 
  -initrd /path/to/your/initramfs.cpio \ 
  ...
```

--------------------------------

### Install Docker using curl

Source: https://unikraft.org/docs/contributing/docs

Installs Docker CE on your system using a curl command. This is a prerequisite for building the Unikraft documentation within a Docker environment.

```shell
curl -fsSL https://get.docker.com/ | sh

```

--------------------------------

### Install Unikraft Packer Plugin

Source: https://unikraft.org/docs/getting-started/integrations/hcp-packer

Installs the Unikraft Packer plugin using the Packer CLI. This command fetches and installs the plugin, making it available for use in Packer configurations.

```bash
packer plugins install github.com/unikraft/unikraft
```

--------------------------------

### Complex Unikraft Configuration Example (YAML)

Source: https://unikraft.org/docs/cli/reference/kraftfile/latest

A comprehensive example combining source location, version, and KConfig options to define a highly specific Unikraft core configuration.

```yaml
spec: v0.6

name: helloworld

unikraft:
  source: https://github.com/unikraft/unikraft.git
  version: stable
  kconfig:
    CONFIG_EXAMPLE: "y"
```

--------------------------------

### Start Unikraft Cloud Instance

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Starts a stopped Unikraft instance in the Unikraft Cloud.

```shell
`kraft cloud instance start`
```

--------------------------------

### Start Unikraft Cloud Compose Services (Up)

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Starts and attaches to services defined in a Unikraft Compose file in the cloud.

```shell
`kraft cloud compose up`
```

--------------------------------

### Install runu Binary from Tarball (Shell)

Source: https://unikraft.org/docs/getting-started/integrations/container-runtimes

Extracts the pre-built runu binary from a tarball and installs it into the system's PATH. This is a common method for deploying the runtime.

```shell
tar -xzvf kraftkit_runu_0.7.0_linux_amd64.tar.gz runu
# PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
sudo install runu /usr/local/bin/
```

--------------------------------

### Connect to Redis and Test

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This demonstrates how to use the `redis-cli` to connect to a Redis server running on localhost at the default port. It includes commands to test the connection with `ping` and basic key-value operations (`set`, `get`).

```bash
redis-cli -h localhost
```

```redis-cli
ping
PONG
set a 1
OK
get a
"1"

```

--------------------------------

### Bring Up Unikraft Cloud Compose Project

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Creates, builds, and starts all services defined in a Unikraft Cloud Compose file on the Unikraft Cloud. A comprehensive deployment command.

```Shell
kraft cloud compose up
```

--------------------------------

### Start and Manage Unikraft Compose Services

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Creates, starts, and attaches to services defined in a Unikraft Compose file.

```shell
`kraft compose up`
```

--------------------------------

### Install KraftKit on Debian/Ubuntu via APT Repository

Source: https://unikraft.org/docs/cli/install

Installs KraftKit on Debian or Ubuntu systems by adding the official Unikraft APT repository. This involves updating package lists, installing prerequisite tools, adding the GPG key, configuring the repository source, and finally installing the kraftkit package.

```bash
sudo apt-get update
sudo apt-get install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release
```

```bash
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.pkg.kraftkit.sh/gpg.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/unikraft.gpg
```

```bash
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/unikraft.gpg] https://deb.pkg.kraftkit.sh /" | \
  sudo tee /etc/apt/sources.list.d/unikraft.list > /dev/null
```

```bash
sudo apt-get update
sudo apt-get install kraftkit
```

--------------------------------

### Install KraftKit on Arch Linux from AUR

Source: https://unikraft.org/docs/cli/install

Installs KraftKit on Arch Linux by cloning the `kraftkit-bin` package from the Arch User Repository (AUR). It involves git cloning the repository, changing into the directory, and then using makepkg to build and install the package.

```bash
git clone https://aur.arch.linux.org/kraftkit-bin.git
cd kraftkit-bin
makepkg -si
```

--------------------------------

### Start Local Unikraft Runtime

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Starts a previously stopped Unikraft instance on the local machine.

```shell
`kraft start`
```

--------------------------------

### Install KraftKit on Fedora/RHEL via RPM Repository

Source: https://unikraft.org/docs/cli/install

Installs KraftKit on Fedora or RHEL-based systems by configuring the RPM package registry. This involves creating a .repo file with the repository details and then using yum to make the cache and install the package.

```ini
[kraftkit]
name=KraftKit Repo
baseurl=https://rpm.pkg.kraftkit.sh
enabled=1
gpgcheck=0
```

```bash
yum makecache
yum install -y kraftkit
```

--------------------------------

### Start Unikraft Cloud Compose Services

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Starts services defined in a Unikraft Compose file in the cloud.

```shell
`kraft cloud compose start`
```

--------------------------------

### Create Cloud Instance

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Creates a new Unikraft instance on the Unikraft Cloud. This command provisions and starts a unikernel in the cloud.

```Shell
kraft cloud instance create
```

--------------------------------

### Start Unikraft Compose Services

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Starts the services defined in a Unikraft Compose file.

```shell
`kraft compose start`
```

--------------------------------

### Makefile.uk example for write system call

Source: https://unikraft.org/docs/internals/syscall-shim

A specific example showing how to register the 'write' system call in `Makefile.uk`. It appends 'write-3' (assuming 'write' has 3 arguments) to the provided syscalls list, controlled by a configuration option.

```makefile
UK_PROVIDED_SYSCALLS-$(CONFIG_LIBVFS})	+= write-3
```

--------------------------------

### Install Individual Linters via npm

Source: https://unikraft.org/docs/contributing/docs

Installs the markdown-cli, textlint, and jscpd linters using npm. These are the linters used by super-linter for the Unikraft documentation repository.

```bash
npm install markdownlint-cli
npm install textlint
npm install jscpd

```

--------------------------------

### Install lychee Binary for Linux

Source: https://unikraft.org/docs/contributing/docs

This snippet outlines the steps to download, extract, and install the lychee binary for Linux. It uses curl to download the release and tar to extract it, placing the executable in a common user binary directory.

```bash
$ pushd /tmp
$ curl -OL https://github.com/lycheeverse/lychee/releases/download/v0.14.3/<release>.tar.gz
$ tar -xf <release>.tar.gz # this would create a `lychee` binary in our current directory
$ mv ./lychee ~/.local/bin # we place the binary in our local home dir path
$ popd
```

--------------------------------

### Example libc-style system call implementation (write)

Source: https://unikraft.org/docs/internals/syscall-shim

An example demonstrating the use of UK_SYSCALL_DEFINE to implement the 'write' system call. It shows how to handle the return value and set errno on error, following the libc convention.

```c
#include <uk/syscall.h>
UK_SYSCALL_DEFINE(ssize_t, write, int, fd, const void *, buf, size_t, count)
{
    ssize_t ret;
    ret = vfs_do_write(fd, buf, count);
    if (ret < 0) {
        errno = EFAULT;
        return -1;
    }
    return ret;
}
```

--------------------------------

### Get Unikraft Help

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

No description

--------------------------------

### Supplying Unikraft Core and Application Arguments

Source: https://unikraft.org/docs/cli/running

This command shows how to provide both Unikraft core arguments and application-level arguments. Unikraft core arguments precede the application arguments, separated by `--`. The example sets a static IPv4 address for the network device and then passes the NGINX configuration file path.

```bash
kraft run unikraft.org/nginx:1.25 netdev.ipv4_addr=172.88.0.2 -- -c /nginx/conf/nginx.conf
```

--------------------------------

### Install Textlint Rules

Source: https://unikraft.org/docs/contributing/docs

Installs essential rules for the textlint linter, specifically 'textlint-rule-terminology' for checking word usage and 'textlint-rule-no-todo' for identifying 'TODO' comments. These rules enhance code quality and consistency.

```bash
npm install textlint-rule-terminology
npm install textlint-rule-no-todo
```

--------------------------------

### Kraftfile Spec Attribute Example

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

Demonstrates the required 'spec' attribute in a Kraftfile, which specifies the version of the Kraftfile syntax. The latest version supported is 'v0.6'.

```yaml
spec: v0.6
```

--------------------------------

### Kraftfile Outdir Attribute Example

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

Shows how to define a custom output directory for build artifacts using the 'outdir' attribute in the Kraftfile. The default location is './.unikraft/build/'.

```yaml
spec: v0.6

outdir: ./out
```

--------------------------------

### Options for `kraft cloud compose create`

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/compose/create

Lists the available options for the `kraft cloud compose create` command, including a help flag.

```bash
-h, --help   help for create

```

--------------------------------

### Kraftfile Cmd Attribute (Inline Array)

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

Demonstrates specifying default arguments for unikernel instantiation as an inline array using the 'cmd' attribute. These arguments are used when the unikernel is started.

```yaml
spec: v0.6

cmd: ["-c", "/nginx/conf/nginx.conf"]
```

--------------------------------

### Display KraftKit Make Help Menu

Source: https://unikraft.org/docs/cli/hacking

Displays the help menu for KraftKit's GNU Make build system. This menu lists available developer-specific targets and their descriptions.

```bash
make help
```

--------------------------------

### Kraftfile Name Attribute Example

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

Illustrates how to specify a name for the unikernel application using the 'name' attribute within the Kraftfile. If not provided, the directory's base name is used.

```yaml
spec: v0.6

name: helloworld
```

--------------------------------

### Unikraft Run Command

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command runs the Unikraft application after it has been built. It removes any existing instances, starts a new one with specified memory and port forwarding, and enables basic logging.

```bash
kraft rm --all
kraft run --log-type basic --log-level debug -M 256M -p 6379:6379 .
```

--------------------------------

### Install Latest Node.js using NVM

Source: https://unikraft.org/docs/contributing/docs

Installs the latest Node.js version using Node Version Manager (nvm). This is recommended as the individual linters may require a more recent Node.js version than the default.

```bash
nvm install node

```

--------------------------------

### Running the Unikraft Rust Tokio Server

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command initiates the Unikraft Rust Tokio server. It pulls the specified Unikraft base image, packages the application, and runs it, exposing port 8080.

```bash
kraft run --log-type basic --log-level debug -p 8080:8080 .
```

--------------------------------

### Define Custom Section in extra.ld

Source: https://unikraft.org/docs/internals/build-system

This linker script example, `extra.ld`, defines a custom section named `.uk_fs_list`. It specifies the start and end symbols (`uk_fslist_start` and `uk_fslist_end`) for this section and ensures that any content placed within `.uk_fs_list` (e.g., from object files) is kept. The section is inserted after the `.text` section in the final executable.

```ld
SECTIONS
{
    .uk_fs_list : { 
         PROVIDE(uk_fslist_start = .);
         KEEP (*(.uk_fs_list))
         PROVIDE(uk_fslist_end = .);
    }
}
INSERT AFTER .text;

```

--------------------------------

### kraft start

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img

The `kraft start` command starts a stopped unikernel. This command initiates a previously stopped unikernel.

```APIDOC
## kraft start

### Description
Starts a stopped unikernel.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Troubleshooting Unikraft Application Startup Failure

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command is used to inspect the debug log file when the Unikraft application fails to start. It helps identify the root cause of the failure, often related to system resource issues.

```bash
cat /home/razvand/.local/share/kraftkit/runtime/ef6a273d-f066-4674-8d06-b85a10068f13/machine.log

```

--------------------------------

### Run Minimal Redis Docker Container

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command starts a Redis container from the 'minimal-redis' image, exposing port 6379 and removing the container upon exit. It utilizes the default Redis configuration.

```bash
docker run --rm -p 6379:6379 minimal-redis /usr/bin/redis-server
```

--------------------------------

### Cloud Instance Commands

Source: https://unikraft.org/docs/cli/reference/kraft/compose/build

Create, manage, and retrieve information about Unikraft cloud instances.

```APIDOC
## Cloud Instance Commands

### Description
Commands for managing Unikraft cloud instances.

### Commands
- **`kraft cloud instance create`**: Create a new cloud instance.
- **`kraft cloud instance get`**: Retrieve details of a specific instance.
- **`kraft cloud instance list`**: List all cloud instances.
- **`kraft cloud instance logs`**: View logs of a cloud instance.
- **`kraft cloud instance remove`**: Remove a cloud instance.
- **`kraft cloud instance start`**: Start a cloud instance.
- **`kraft cloud instance stop`**: Stop a cloud instance.
```

--------------------------------

### Configure KConfig Options (YAML)

Source: https://unikraft.org/docs/cli/reference/kraftfile/v0

Demonstrates how to set KConfig options for Unikraft using both list-style and map-style formatting within the YAML configuration.

```yaml
unikraft:
  kconfig:
  - CONFIG_EXAMPLE=y
spec: v0.6
name: helloworld
```

```yaml
unikraft:
  kconfig:
    CONFIG_EXAMPLE: "y"
```

--------------------------------

### Cloning and Navigating Application Repository in GitLab CI

Source: https://unikraft.org/docs/getting-started/integrations/gitlab

Manually sets up the development environment within the GitLab CI runner. Clones the 'unikraft/app-helloworld' repository into '/tmp/app-helloworld' and changes the current directory to the cloned repository.

```shell
mkdir /tmp/app-helloworld
git clone https://github.com/unikraft/app-helloworld.git /tmp/app-helloworld
cd /tmp/app-helloworld
```

--------------------------------

### Kraftfile Command for Redis Server

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This `cmd` option within the Kraftfile specifies the command to execute when the Unikraft image runs. It ensures that the redis-server starts and uses the provided configuration file.

```yaml
cmd: ["/usr/bin/redis-server", "/etc/redis.conf"]
```

--------------------------------

### kraft help

Source: https://unikraft.org/docs/cli/reference/kraft/start

Displays help information for Unikraft commands.

```APIDOC
## kraft help

### Description
Displays general help information for the Unikraft CLI or help for specific commands.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### Path Parameters
- **[command]** (string) - Optional - The specific command for which to display help.

#### Query Parameters
None

#### Flags
- **-h, --help** (boolean) - Optional - Display help information for the help command.

### Request Example
```bash
# Display general help
$ kraft help

# Display help for the 'build' command
$ kraft help build
```

### Response
#### Success Response (0)
- Help text for the specified command or general usage information.

#### Response Example
```
Usage:
  kraft [command]

Available Commands:
  build       Build unikernel project
  clean       Clean build artifacts
  completion  Generate shell completion scripts
  compose     Manages multi-unikernel applications
  cloud       Manages Unikraft deployments in the cloud
  help        Help about any command
  install     Install Unikraft CLI companion tool
  lib         Manages unikernel libraries
  login       Logs into the Unikraft cloud platform
  menu        Configure unikernel options
  pkg         Manages unikernel packages
  ps          List running machines
  remove      Remove a machine
  run         Run a unikernel
  start       Start one or more machines
  stop        Stop one or more machines
  version     Display Unikraft CLI version

Flags:
  -h, --help   help for kraft

Use "kraft [command] --help" for more information about a command.
```
```

--------------------------------

### Basic Unikraft Build with GitHub Actions

Source: https://unikraft.org/docs/getting-started/integrations/github-actions

This example demonstrates a basic GitHub Actions workflow to build a unikernel application. It checks out the repository and uses the unikraft/kraftkit action to build the project based on a Kraftfile, specifying the architecture and platform.

```yaml
name: example1

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  build:
    steps:
    - uses: actions/checkout@v3


    - uses: unikraft/kraftkit@stable
      with:
        workdir: .
        kraftfile: Kraftfile
        arch: x86_64
        plat: qemu

```

--------------------------------

### Build Kraft Binary

Source: https://unikraft.org/docs/cli/hacking

Builds the `kraft` binary using the `make kraft` command. This requires Go 1.20 or later to be installed on the host system. The resulting binary is placed in the `dist/` directory.

```bash
make kraft
```

--------------------------------

### KraftKit Build, Run, and Package Workflow (Shell)

Source: https://unikraft.org/docs/getting-started/integrations/gitlab

This script demonstrates a complete workflow for building, running, and packaging a Unikraft application. It includes cloning a repository, building the application for a specific architecture and platform, running it, and packaging it as an OCI image. Dependencies include KraftKit and Git.

```shell
variables:
  KRAFTKIT_LOG_LEVEL: debug
  KRAFTKIT_LOG_TYPE: basic
  KRAFTKIT_NO_CHECK_UPDATES: "true"


build-run-job:
  image:
    name: "kraftkit.sh/base:latest"
    entrypoint: [""]
  script: |
    set -xe
    
    # Printing version
    kraft version


    # Cloning repository
    mkdir /tmp/app-helloworld
    git clone https://github.com/unikraft/app-helloworld.git /tmp/app-helloworld
    cd /tmp/app-helloworld


    # Building app helloworld
    kraft build --no-cache --arch x86_64 --plat qemu


    # Running app helloworld
    kraft run -W -M 256M --arch x86_64 --plat qemu


    # Packaging app helloworld
    mkdir fs0
    touch fs0/file.txt
    kraft pkg --name my.own.repository.com/helloworld:latest --as oci --initrd fs0/ --arch x86_64 --plat qemu


    # Login to repository
    # kraft login -u $MY_SECRET_USER -t $MY_SECRET_PASSWORD


    # Pushing app helloworld
    # kraft pkg push --as oci my.own.repository.com/helloworld:latest

```

--------------------------------

### Run 'Hello, World' Unikernel

Source: https://unikraft.org/docs/cli

Executes a pre-built 'Hello, World' unikernel using the `kraft run` command. This serves as a basic test to verify the installation and functionality of the Unikraft CLI. The command requires the `unikraft.org/helloworld:latest` image to be available.

```shell
kraft run unikraft.org/helloworld:latest
```

--------------------------------

### Packaging and Pushing OCI Images with GitHub Actions

Source: https://unikraft.org/docs/getting-started/integrations/github-actions

This example illustrates how to package a unikernel build into an OCI image and push it to a container registry (e.g., GHCR). It includes steps for logging into the registry using docker/login-action and specifying the output format and push command.

```yaml
name: example5

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  build:
    steps:
    - uses: actions/checkout@v3


    - name: Login to OCI registry
      uses: docker/login-action@v2
      with:
        registry: ghcr.io
        username: ${{ secrets.REG_USERNAME }}
        password: ${{ secrets.REG_TOKEN }}


    - uses: unikraft/kraftkit@stable
      with:
        workdir: .
        kraftfile: Kraftfile
        arch: x86_64
        plat: qemu
        output: oci://ghcr.io/username/repo:latest
        push: true

```

--------------------------------

### Unikraft Cloud Instance Commands

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/compose

Commands for managing Unikraft instances in the cloud. This allows for creating, retrieving details, listing, viewing logs, removing, starting, and stopping cloud instances.

```bash
kraft cloud instance create

kraft cloud instance get

kraft cloud instance list

kraft cloud instance logs

kraft cloud instance remove

kraft cloud instance start

kraft cloud instance stop
```

--------------------------------

### Cloud Instance Commands (Kraft CLI)

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/scale/add

Commands for managing Unikraft instances in the Unikraft Cloud. This includes creating, retrieving, listing, managing logs, removing, starting, and stopping instances.

```bash
`kraft cloud instance create`
`kraft cloud instance get`
`kraft cloud instance list`
`kraft cloud instance logs`
`kraft cloud instance remove`
`kraft cloud instance start`
`kraft cloud instance stop`
```

--------------------------------

### Dockerfile for Minimized Python Environment

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This Dockerfile constructs a minimized Python environment. It first sets up a base Python image, installs dependencies from requirements.txt, and then copies the application code. The final stage uses 'scratch' to create a minimal image containing only the necessary Python libraries and the application file.

```dockerfile
FROM python:3.10.11 AS base


WORKDIR /app


COPY requirements.txt /app


RUN pip3 install -r requirements.txt --no-cache-dir


FROM scratch


COPY --from=base /usr/local/lib/python3.10 /usr/local/lib/python3.10
COPY ./server.py /app/server.py
```

--------------------------------

### Start Local Runtime

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/volume/list

Starts a stopped Unikraft instance locally. Resumes execution of a previously paused or stopped unikernel.

```Shell
kraft start
```

--------------------------------

### Unikraft CLI Command Overview

Source: https://unikraft.org/docs/cli

Provides a comprehensive list of available commands for the Unikraft CLI, categorized into Build, Project Library, Packaging, Local Runtime, Local Networking, Local Volume, Compose, Unikraft Cloud, and Unikraft Cloud Image operations. This helps users discover and utilize the full capabilities of the CLI.

```shell
kraft build                   Configure and build Unikraft unikernels
kraft clean                   Remove the build object files of a Unikraft project
kraft menu                    Open's Unikraft configuration editor TUI

# PROJECT LIBRARY COMMANDS
kraft lib add                 Add unikraft library to the project directory
kraft lib create              Initialize a library from a template
kraft lib remove              Removes a library dependency from the project directory

# PACKAGING COMMANDS

```

```shell
kraft pkg                     Package and distribute Unikraft unikernels and their dependencies

```

```shell
kraft pkg info                Show information about a package

```

```shell
kraft pkg list                List installed Unikraft component packages

```

```shell
kraft pkg pull                Pull a Unikraft unikernel and/or its dependencies

```

```shell
kraft pkg push                Push a Unikraft unikernel package to registry

```

```shell
kraft pkg remove              Removes selected local packages

```

```shell
kraft pkg source              Add Unikraft component manifests

```

```shell
kraft pkg unsource            Remove Unikraft component manifests

```

```shell
kraft pkg update              Retrieve new lists of Unikraft components, libraries and packages

# LOCAL RUNTIME COMMANDS

```

```shell
kraft logs                    Fetch the logs of a unikernel

```

```shell
kraft pause                   Pause one or more running unikernels

```

```shell
kraft ps                      List running unikernels

```

```shell
kraft remove                  Remove one or more running unikernels

```

```shell
kraft run                     Run a unikernel

```

```shell
kraft start                   Start one or more machines

```

```shell
kraft stop                    Stop one or more running unikernels

# LOCAL NETWORKING COMMANDS

```

```shell
kraft net create              Create a new machine network

```

```shell
kraft net down                Bring a network offline

```

```shell
kraft net inspect             Inspect a machine network

```

```shell
kraft net list                List machine networks

```

```shell
kraft net remove              Remove a network

```

```shell
kraft net up                  Bring a network online

# LOCAL VOLUME COMMANDS

```

```shell
kraft vol create              Create a machine volume

```

```shell
kraft vol inspect             Inspect a machine volume

```

```shell
kraft vol ls                  List machine volumes

```

```shell
kraft vol remove              Remove a volume

# COMPOSE COMMANDS

```

```shell
kraft compose build           Build or rebuild services

```

```shell
kraft compose create          Create a compose project

```

```shell
kraft compose down            Stop and remove a compose project

```

```shell
kraft compose logs            Print the logs of services in a project

```

```shell
kraft compose ls              List compose projects

```

```shell
kraft compose pause           Pause a compose project

```

```shell
kraft compose ps              List running services of current project

```

```shell
kraft compose pull            Pull images of services of current project

```

```shell
kraft compose push            Push images of services of current project

```

```shell
kraft compose start           Start a compose project

```

```shell
kraft compose stop            Stop a compose project

```

```shell
kraft compose unpause         Unpause a compose project

```

```shell
kraft compose up              Run a compose project

# UNIKRAFT CLOUD COMMANDS

```

```shell
kraft cloud deploy            Deploy your application

```

```shell
kraft cloud quotas            View your resource quota on Unikraft Cloud

```

```shell
kraft cloud tunnel            Forward a local port to an unexposed instance

# UNIKRAFT CLOUD IMAGE COMMANDS

```

```shell
kraft cloud img list          List all images at a metro for your account

```

```shell
kraft cloud img remove        Remove an image

# UNIKRAFT CLOUD INSTANCE COMMANDS

```

```shell
kraft cloud instance create   Create an instance

```

```shell
kraft cloud instance get      Retrieve the state of instances

```

```shell
kraft cloud instance list     List instances

```

```shell
kraft cloud instance logs     Get console output of instances

```

```shell
kraft cloud instance remove   Remove instances

```

```shell
kraft cloud instance start    Start instances

```

```shell
kraft cloud instance stop     Stop instances

```

```shell
kraft cloud instance top      Show instance metrics

# UNIKRAFT CLOUD VOLUME COMMANDS

```

--------------------------------

### Start BuildKit Daemon in Docker Container (Shell)

Source: https://unikraft.org/docs/cli/filesystem

Starts the BuildKit daemon in a detached Docker container with the name 'buildkitd'. This is required for using Dockerfiles as root filesystems with KraftKit.

```shell
docker run -d --privileged --name buildkitd moby/buildkit:latest
```

--------------------------------

### Create Unikraft Cloud Instance

Source: https://unikraft.org/docs/cli/reference/kraft/cloud/img/list

Launches a new Unikraft instance in the Unikraft Cloud.

```shell
`kraft cloud instance create`
```

--------------------------------

### Build KraftKit Developer Environment Locally

Source: https://unikraft.org/docs/cli/hacking

Builds the `myself-full` developer environment container image locally using a Make target. This image includes all tools required for building KraftKit.

```bash
make buildenv-myself-full
```

--------------------------------

### Build Minimal Redis Docker Image

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command initiates the Docker build process using the Dockerfile in the current directory. It tags the resulting image as 'minimal-redis', creating a streamlined Redis environment.

```bash
docker build --tag minimal-redis .
```

--------------------------------

### Testing Run-to-Completion Unikernels with GitHub Actions

Source: https://unikraft.org/docs/getting-started/integrations/github-actions

This example shows how to configure the Unikraft GitHub Action to execute run-to-completion type unikernels. By setting `execute: true`, the action will run the unikernel in emulation mode (QEMU TCG), which is useful for tasks like running test suites.

```yaml
name: example3

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  build:
    steps:
    - uses: actions/checkout@v3


    - uses: unikraft/kraftkit@stable
      with:
        workdir: .
        kraftfile: Kraftfile
        arch: x86_64
        plat: qemu
        execute: true

```

--------------------------------

### Dockerfile for building and minimizing http-tokio

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This Dockerfile defines a multi-stage build process. The first stage compiles the http-tokio application using the rust toolchain. The second stage creates a minimal scratch environment and copies only the compiled server binary, reducing the final image size.

```dockerfile
FROM rust:1.73.0-bookworm AS build


WORKDIR /src


COPY ./src /src/src
COPY ./Cargo.toml /src/Cargo.toml


RUN cargo build


FROM scratch


# Server binary
COPY --from=build /src/target/debug/http-tokio /server

```

--------------------------------

### Install strace in Debian-based Container

Source: https://unikraft.org/docs/contributing/adding-to-the-app-catalog

This command sequence updates the package list and installs the `strace` utility within a Debian-based Docker container. `strace` is used to trace system calls, which helps in identifying file dependencies.

```bash
root@8b346198f54d:/data# apt update
root@8b346198f54d:/data# apt install -y strace
```

--------------------------------

### Running Unikraft Application with KraftKit CLI

Source: https://unikraft.org/docs/getting-started/integrations/gitlab

Runs the 'helloworld' Unikraft application using the 'kraft run' command. '-W' disables acceleration, '-M 256M' sets memory to 256MB, '--arch x86_64' specifies the architecture, and '--plat qemu' sets the platform.

```shell
# Running app helloworld
craft run -W -M 256M --arch x86_64 --plat qemu
```
Tokens:
Raw