Get up and running with Ravel in minutes.
Before installing Ravel, ensure you have:
- Linux System (tested on Ubuntu 20.04+, Debian 11+)
- KVM enabled (
lsmod | grep kvm) - TUN/TAP kernel module enabled
- Root access for installation
- Go 1.22+ (for building from source)
- Cloud Hypervisor binary
# Download and install the latest release
curl -fsSL https://raw.githubusercontent.com/alexisbouchez/ravel/master/install.sh | sudo bash
# Verify installation
ravel version# Clone the repository
git clone https://github.com/alexisbouchez/ravel.git
cd ravel
# Build all binaries
make build-all
# Install binaries
sudo make install# Download Cloud Hypervisor
wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v38.0/cloud-hypervisor-static
chmod +x cloud-hypervisor-static
sudo mv cloud-hypervisor-static /opt/ravel/cloud-hypervisor
# Download Linux kernel
wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v38.0/vmlinux
sudo mv vmlinux /opt/ravel/vmlinux.bin# Install containerd for image management
sudo apt-get update
sudo apt-get install -y containerd
# Start containerd
sudo systemctl enable containerd
sudo systemctl start containerd# Install NATS Server
wget https://github.com/nats-io/nats-server/releases/download/v2.10.7/nats-server-v2.10.7-linux-amd64.tar.gz
tar -xzf nats-server-v2.10.7-linux-amd64.tar.gz
sudo mv nats-server-v2.10.7-linux-amd64/nats-server /usr/local/bin/
# Start NATS
nats-server &Create a configuration file at /etc/ravel/config.toml:
[daemon]
database_path = "/var/lib/ravel/daemon.db"
[daemon.runtime]
cloud_hypervisor_binary = "/opt/ravel/cloud-hypervisor"
jailer_binary = "/opt/ravel/jailer"
init_binary = "/opt/ravel/initd"
linux_kernel = "/opt/ravel/vmlinux.bin"
[daemon.agent]
resources = { cpus_mhz = 8000, memory_mb = 8192 }
node_id = "node-1"
region = "local"
address = "127.0.0.1"
port = 8080
[server]
postgres_url = "postgres://user:pass@localhost:5432/ravel"
[server.api]
address = ":3000"
[server.machine_templates.std]
vcpu_frequency = 2500
combinations = [
{ vcpus = 1, memory_configs = [512, 1024, 2048] },
{ vcpus = 2, memory_configs = [1024, 2048, 4096] },
]sudo mkdir -p /var/lib/ravel
sudo mkdir -p /opt/ravel
sudo mkdir -p /etc/ravel# Start the daemon (manages runtime and agent)
sudo ravel daemon -c /etc/ravel/config.toml# Setup PostgreSQL database
createdb ravel
psql ravel < schema.sql
# Start the server (API and orchestrator)
ravel server -c /etc/ravel/config.toml# Create a namespace
curl -X POST http://localhost:3000/api/v1/namespaces \
-H "Content-Type: application/json" \
-d '{"name": "default"}'
# Create a fleet
curl -X POST http://localhost:3000/api/v1/namespaces/default/fleets \
-H "Content-Type: application/json" \
-d '{"name": "my-fleet"}'
# Create a machine
curl -X POST http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines \
-H "Content-Type: application/json" \
-d '{
"region": "local",
"config": {
"image": "docker.io/library/alpine:latest",
"guest": {
"cpu_kind": "std",
"cpus": 1,
"memory_mb": 512
},
"workload": {
"init": {
"cmd": ["/bin/sh", "-c", "echo Hello from Ravel && sleep 3600"],
"user": "root"
}
}
}
}'# List machines in fleet
curl http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines
# Get specific machine
curl http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines/{machine-id}curl -X POST http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines/{machine-id}/exec \
-H "Content-Type: application/json" \
-d '{
"cmd": ["echo", "Hello from inside the machine"],
"timeout_ms": 5000
}'- Volumes: Add persistent storage
- Health Checks: Monitor machine health
- Private Networks: Secure inter-machine communication
- Secrets: Manage sensitive data
Check out the examples directory for common configurations:
- hello-world.json - Basic machine
- volumes-example.json - With persistent storage
- healthcheck-example.json - With health monitoring
- private-network.json - With encrypted networking
For production deployments:
- Enable TLS for cluster communication
- Setup PostgreSQL with replication
- Configure NATS cluster
- Enable monitoring and logging
See Production Deployment for detailed instructions.
# Check daemon logs
sudo journalctl -u ravel-daemon -f
# Check machine events
curl http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines/{machine-id}# Verify network configuration
ip addr show
# Check iptables rules
sudo iptables -L -n -v
# Test connectivity
ping {machine-ip}# Verify containerd is running
sudo systemctl status containerd
# Check containerd logs
sudo journalctl -u containerd -f
# Manually pull image
sudo ctr image pull docker.io/library/alpine:latest# Build Ravel
make build-all
# Run tests
make test
# Start daemon in debug mode
sudo ravel daemon -c config.toml --debug
# View all machines across namespaces
curl http://localhost:3000/api/v1/machines
# Stop a machine
curl -X POST http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines/{machine-id}/stop
# Destroy a machine
curl -X DELETE http://localhost:3000/api/v1/namespaces/default/fleets/my-fleet/machines/{machine-id}- Documentation: docs/
- GitHub Issues: github.com/alexisbouchez/ravel/issues
- Discord: Join our Discord
- Read the Architecture guide to understand how Ravel works
- Learn about Configuration options
- Explore Features in depth
- Deploy to Production