Installing kraft
To get started, please install the kraft
command-line client which is used for
defining, configuring, building, and running Unikraft applications. Installation
can be performed in a number of different ways depending on your preferences or
system requirements.
Debian/Ubuntu
Prerequisites
- Debian Buster (10)
- Debian Stretch (9)
- Ubuntu Focal (20.04) LTS
- Ubuntu Bionic (18.04) LTS
- Ubuntu Xenial (16.04) LTS
Installation Instructions
The process for installing kraft
on Debian or Ubuntu is straight forward and
we recommend using our hosted APT managed repository to access the latest
updates.
-
Update the APT package index and install packages to allow APT to use a repository over HTTPS:
$ sudo apt install \ apt-transport-https \ ca-certificates \ software-properties-common \ curl \ gnupg2
-
Add the Linux-distribution GPG key:
$ curl -fsSL https://releases.unikraft.org/linux/gpg | sudo apt-key add -
-
Verify that you now have the key with the following fingerprint:
$ apt-key fingerprint 8D14C246 pub rsa4096 2020-10-22 [SC] [expires: 2024-10-22] DCE2 072B 5FAE 29BF F78C 9AED 5989 A47D 8D14 C246 uid [ unknown] Unikraft <[email protected]> uid [ unknown] Unikraft Monkey <[email protected]> sub rsa4096 2020-10-22 [E] [expires: 2024-10-22]
-
Add the remote repository by using the following command for Debian:
$ sudo add-apt-repository \ "deb [arch=amd64] http://releases.unikraft.org/linux/debian \ $(lsb_release -cs) \ stable"
Or, for Ubuntu:
$ sudo add-apt-repository \ "deb [arch=amd64] http://releases.unikraft.org/linux/ubuntu \ $(lsb_release -cs) \ stable"
Note: To add thestaging
branch of the kraft repository, remove or append to the “stable
” branch-name keyword. -
Update the APT package index on your machine and install
unikraft-tools
:$ sudo apt-get update $ sudo apt-get install unikraft-tools
This will install
kraft
along with additional packages required to build a Unikraft unikernel, includinggcc
,make
, etc.
Docker
You can use the container environment for kraft
if you do not wish to install
all the dependencies which are required for building Unikraft unikernels.
Typically, this includes gcc
, make
and friends in order to compile a
unikernel application as well as hypervisor toolchain, such as qemu-system-x86
in order to instantiate the unikernel itself.
To quickly get started with a known working environment, you can use the kraft Docker environment, which can be a good starting ground and workspace.
Prerequisites
Ensure that Docker has been installed on your machine.
Installation Instructions
To simply get started, attach a workspace as a volume to the kraft container image like so:
$ docker run -it --rm \
-v $(pwd):/usr/src/unikraft \
--entrypoint bash
unikraft/kraft:staging
This will attach you to a new workspace environment where you can begin using
kraft
. There are two versions of the kraft
Docker environment, with the
following tags:
unikraft/kraft:staging
contains the latest staging version ofkraft
and is continiously updated with new commits to this branch; and,unikraft/kraft:latest
which contains the latest stable version ofkraft
.
It is possible to launch Unikraft unikernels via this container environment by mounting the correct paths to your VMM sockets. For example, with KVM and QEMU you can launch the container environment like so:
$ docker run -it --rm \
-v $(pwd):/usr/src/unikraft \
--device /dev/kvm
--entrypoint bash
unikraft/kraft:staging
With pip
To install kraft
manually using the python toolchain, you can do this easily
too by specifying the install location of the repository from
GitHub:
pip3 install git+https://github.com/unikraft/kraft.git
Install to hack
If you have found a bug, issue or wish to extend the kraft codebase, then simply clone the repository and install kraft in “edit mode”:
git clone https://github.com/unikraft/kraft.git
pip3 install -e ./kraft
More information about kraft
’s internal build system can be found by
running make help
within the repository:
Usage: [FLAGS=...] make TARGET
kraft's build system is designed to help package, test and release the
unikraft-tools software suite. To find out more information about a specfic
target listed below, use:
make help TARGET
If you are trying to install kraft, please refer to our getting started
guide: https://unikraft.org/getting-started. If you are a developer wishing
to make changes to kraft, please refer to the CONTRIBUTING.md document
located in this repository.
General targets:
install Install kraft and other unikraft tools.
clean Clean build artifacts excluding packages.
properclean Clean everything.
get-version Show the current version of the application.
help Show this help menu.
Developer targets:
release-commit Commit and tag a release to the repository.
changelog Produce a changelog based on the git log.
bump Increment kraft's release version in the source
repository.
Docker container build targets:
docker-gcc Build gcc and binutils in Docker container.
docker-qemu Build qemu in a Docker container.
docker-kraft Build the kraft Docker container.
docker-linuxk Build the Linux kernel in a container.
docker-pkg-deb Build a Debian-based packaging environment.
docker-pkg-deb-all Build all Deban-based packaging environments.
Packaging targets:
sdist Produce a distributable tarball of the source tree.
pkg-deb Produce a Debian-based package.
Test targets:
test Run all test targets.
test-all Alias for 'make test'.
test-lint Perform a syntax check on kraft.
test-pkg Test the installation of kraft packages.
test-unit Run all defined unit tests.
test-coverage Generate a coverage report.
test-docker-pkg-deb Test the installation of a Debian-based package.
test-docker-pkg-deb-all Test the installation of all Debian-based packages.
Docker proxy:
Some targets are automatically proxied via a Docker container so as to
ensure consistency between runtime environments. To turn off proxying
targets via Docker, ensure that requirements-dev.txt has been satisfied then
simply unset the DOCKER variable, for example:
DOCKER= make test
Help:
For help using this tool, please open an issue on the Github repository:
https://github.com/unikraft/kraft or send an email to our maling list:
<[email protected]>.
git
, make
, ncurses, flex
, wget
,
unzip
, tar
, python3
(including setuptools
) and gcc
.
Details on how to configure how kraft
interacts with gcc and the Unikraft
build system in addition on how to use kraft
with Docker is covered in
:ref:advanced_usage
.