runtime-setup.md

The Ravel Runtime

The Ravel Runtime is the most low-level component of Ravel. It is responsible for running the OCI images provided by the Ravel Agent / Daemon inside cloud-hypervisors VMs.

The Ravel Runtime uses three main components to run the VMs:

• Containerd: to manage the OCI images as VM rootfs with the devmapper snapshotter.
• Cloud-hypervisor: to run the VMs.
• The ravel Jailer to further isolate the VMs inside cgoups, mount, pid and network namespaces
• Initd: injected as the init process of the VMs to run the user provided entrypoint.

Getting started

Prerequisites

Note: For now Ravel only supports Linux amd64 architectures with support for KVM.

1. KVM

Before anything, you need to check that your system is KVM enabled. You can do this by running the following command:

$ lsmod | grep kvm # Check the presence of the kvm module
# or
$ kvm-ok # if installed

2. TUN/TAP device You need to enable the TUN/TAP device driver on your system. You can follow instructions from the Linux Kernel documentation here:

mkdir /dev/net (if it doesn't exist already)
mknod /dev/net/tun c 10 200

3. Cloud-hypervisor You can download the Cloud-hypervisor v43.0 release on github. You MUST download the statically linked binary. Then you can make it available at /opt/ravel/cloud-hypervisor

4. Containerd installed and configured to run with the devmapper snapshotter.

5. NATS Server (for cluster mode)

For running Ravel in cluster mode, you need a NATS server. You can install it using one of the following methods:

Using package manager:

# Ubuntu/Debian
curl -L https://github.com/nats-io/nats-server/releases/latest/download/nats-server-linux-amd64.tar.gz | tar xz
sudo mv nats-server /usr/local/bin/

# Or using Docker
docker run -p 4222:4222 -p 8222:8222 nats:latest

Basic NATS server configuration:

# Start NATS server with default settings
nats-server

# Or with custom port
nats-server -p 4222

For production deployments, refer to the NATS documentation for advanced configuration including clustering, authentication, and TLS.

Install Ravel

1. Download the latest release of Ravel from the releases page.

2. Extract the archive and move the binaries to your PATH:

mkdir -p /opt/ravel
mkdir -p /etc/ravel
pushd $(mktemp -d)
tar -xvf ravel ravel_0.7.2_linux_amd64.tar.gz
mv -t /usr/sbin/ ravel
mv -t /opt/ravel jailer initd
popd

2. Testing the installation

$ ravel
A cli tool for managing raveld.

Usage:
  ravel [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  daemon      Start the Ravel daemon
  db          Database management commands
  disks       Manage disks
  help        Help about any command
  image       Manage images
  instance    Manage ravel instances
  server      Start the API server
  tls         Ravel TLS certificates management for mTLS

Flags:
      --debug   Enable debug logging
  -h, --help    help for ravel

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

3. Build the cloud-hypervisor linux kernel by following the cloud-hypervisor documentation. Then, make the uncompressed file available at /opt/ravel/vmlinux.bin.

Configuration

In /etc/ravel/config.toml you can configure the Ravel Agent. Here is an example configuration:

[daemon]
database_path = "/var/lib/ravel/agent.db"
[daemon.runtime]
init_binary = "/opt/ravel/initd"
jailer_binary = "/opt/ravel/jailer"
cloud_hypervisor_binary = "./cloud-hypervisor"
linux_kernel = "./vmlinux.bin"

To learn more about the configuration options, see the configuration documentation.

Running the Ravel Daemon

To start the Ravel Daemon, run the following command:

sudo ravel daemon [-c /etc/ravel/config.toml]

Then you can try to create a new instance with the following command:

ravel instance create -c instance.json

You can find an instance configuration example in the examples directory.