Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add readme #38

Merged
merged 9 commits into from
May 2, 2024
Merged
Show file tree
Hide file tree
Changes from 6 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
141 changes: 141 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
<div style="text-align:center">
<h1> Cloudlet</h1>
<p>The almost fast FaaS</p>
<img src="./assets/demo.gif" alt="Demo" />
</div>

## Table of Contents

- [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Run Locally](#run-locally)
- [Clone the project](#clone-the-project)
- [Setup](#setup)
- [Start the VMM](#start-the-vmm)
- [Run the API](#run-the-api)
- [Send the request using the cli](#send-the-request-using-the-cli)
- [Architecture](#architecture)
- [Config file](#config-file)

## Prerequisites

Basic dependencies (with apt):

```bash
apt install build-essential cmake pkg-config libssl-dev flex bison libelf-dev
```

Others:

- add rust musl target: `rustup target add x86_64-unknown-linux-musl`
- add protoc binary: see [`github.com/protocolbuffers/protobuf`](https://github.com/protocolbuffers/protobuf)
- [just](https://github.com/casey/just): `cargo install just`
thomas-mauran marked this conversation as resolved.
Show resolved Hide resolved

## Run Locally

### Clone the project

```bash
git clone https://github.com/virt-do/cloudlet
```

### Setup

Go to the project directory:

```bash
cd cloudlet
```

Create a TOML config file or update the [existing one](./src/agent/examples/config.toml):

```bash
cat << EOF > src/agent/examples/config.toml
workload-name = "fibonacci"
language = "rust"
action = "prepare-and-run"

[server]
address = "localhost"
port = 50051

[build]
source-code-path = "$(readlink -f ./src/agent/examples/main.rs)"
release = true
EOF
```

Make sure to update the source-code-path to the path of the source code you want to run.
thomas-mauran marked this conversation as resolved.
Show resolved Hide resolved
Use an absolute path.

[Here](#config-file) are more informations about each field

### Start the VMM

> [!WARNING]
> Make sure to replace $CARGO_PATH with the path to your cargo binary
thomas-mauran marked this conversation as resolved.
Show resolved Hide resolved
>
> ```bash
> export CARGO_PATH=$(which cargo)
> ```

```bash
sudo -E capsh --keep=1 --user=$USER --inh=cap_net_admin --addamb=cap_net_admin -- -c 'RUST_BACKTRACE=1 '$CARGO_PATH' run --bin vmm -- grpc'
```

### Run the API

```bash
cargo run --bin api
```

### Send the request using the cli
thomas-mauran marked this conversation as resolved.
Show resolved Hide resolved

```bash
cargo run --bin cli run --config-path src/agent/examples/config.toml
thomas-mauran marked this conversation as resolved.
Show resolved Hide resolved
```

> [!NOTE]
> If it's your first time running the request, `cloudlet` will have to compile a kernel and an initramfs image.
> This will take a while, so make sure you do something else while you wait...

## Architecture

Here is a simple sequence diagram of Cloudlet:

```mermaid
sequenceDiagram
participant CLI
participant API
participant VMM
participant Agent

CLI->>API: HTTP Request /run
API->>VMM: gRPC Request to create VM
VMM->>Agent: Creation of the VM
VMM->>Agent: gRPC Request to the agent
Agent->>Agent: Build and run code
Agent-->>VMM: Stream Response
VMM-->>API: Stream Response
API-->>CLI: HTTP Response
```

1. The CLI sends an HTTP request to the API which in turn sends a gRPC request to the VMM
2. The VMM then creates a VM
3. When a VM starts it boots on the agent which holds another gRPC server to handle requests
4. The agent then builds and runs the code
5. The response is streamed back to the VMM and then to the API and finally to the CLI.

## Config file

table:

thomas-mauran marked this conversation as resolved.
Show resolved Hide resolved
| Field | Description | Type |
| --- | --- | --- |
| workload-name | Name of the workload you wanna run | String |
| language | Language of the source code | String enum: rust, python node |
| action | Action to perform | String enum: prepare-and-run |
| server.address | Address of the server (currently not used) | String |
| server.port | Port of the server (currently not used) | Integer |
| build.source-code-path | Path to the source code on your local machine | String |
| build.release | Build the source code in release mode | Boolean |
Binary file added assets/demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.