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

feature: docs advanced #12

Merged
merged 4 commits into from
Nov 20, 2023
Merged
Show file tree
Hide file tree
Changes from all 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
3 changes: 2 additions & 1 deletion pages/docs/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,6 @@
},
"index": "Introduction",
"getting-started": "Getting Started",
"user-guide": "User Guide"
"user-guide": "User Guide",
"advanced": "Advanced"
}
5 changes: 5 additions & 0 deletions pages/docs/advanced/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"project-structure": "Project structure",
"how-it-works": "How it works ?",
"getting-involved": "Getting Involved"
}
39 changes: 39 additions & 0 deletions pages/docs/advanced/getting-involved.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Getting Involved

Your interest in joining the Faast community and contributing to our open-source
journey is highly appreciated. Here are the steps you need to follow to
contribute effectively to the project.

## How to Start?

1. **Get Familiar with the Project**:

Before you start, make sure you have a clear understanding of what the project
aims to achieve and the guidelines you need to follow. This ensures that your
contributions are in line with the project’s goals.

- Read the documentation to understand how Faast works.
- Take a look at our [GitHub repository](https://github.com/faast-rt/lambdo) to
see how the project is structured.

2. **Set Up Your Development Environment**:

Ensure that you have all the necessary tools and dependencies installed to work
on the project. Setting up your environment correctly helps prevent issues down
the line.

- Follow our
[installation guide](https://faast-rt.com/docs/getting-started/installation)

## How to Contribute?

Please ensure you read and adhere to our
[Contributing Guide](https://github.com/faast-rt/lambdo/blob/main/CONTRIBUTING.md)
to streamline the process and align your contributions with the project's
standards.

## Code of Conduct

We want Faast to be a welcoming and respectful environment. Please read and
follow our
[Code of Conduct](https://github.com/faast-rt/lambdo/blob/main/CODE_OF_CONDUCT.md).
37 changes: 37 additions & 0 deletions pages/docs/advanced/how-it-works.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
import Image from 'next/image';
import Architecture from '../../../public/images/architecture.png';

## How it works ?

<div className="col-span-2 flex items-center justify-center py-2">
<Image src={Architecture} alt="Lambdo Architecture" />
</div>

Lambdo is structured into three main components:

### 1. Initramfs CLI

The CLI is responsible for generating initial RAM file systems (initramfs)
utilized by the virtual machines (VMs).

### 2. API

The API component consists of several parts:

- **HTTP Server**: This server listens to user code execution requests,
processing incoming requests, and forwarding them to the VM manager.

- **VM Manager**: The VM manager maintains a record of all previously launched
VMs and can initiate the creation of new VMs using "Lumper" if no VMs are
currently available. Additionally, it includes a gRPC server that allows VMs
to register themselves with the VM manager once they have started, as well as
a gRPC client for sending code execution requests to available VMs.

### 3. Agent

The agent runs inside the VMs and is comprised of both a gRPC client and server.
Within the agent, the runner engine takes care of tasks such as creating code
files, executing code, and retrieving the output.

The VMs are launched using "Lumper" and are equipped with a Linux kernel built
along with the previously generated initramfs.
99 changes: 99 additions & 0 deletions pages/docs/advanced/project-structure.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Project Structure

## Agent

The `agent` directory contains the code necessary to generate the agent that
executes within the Virtual Machine (VM) and is responsible for executing the
code.

### build.rs

The `build.rs` file is responsible for constructing the proto file used by both
the server and the client for gRPC communication outside of the VM.

### lib

Inside the `lib` directory, you will find:

#### API

The `API` folder contains the code required to create both a gRPC client and
server using tonic, as well as the definition of the gRPC fields. These
definitions are generated by the `build.rs` file. Note that `grpc_definition.rs`
is an automatically generated file and should not be modified manually.

#### Runner Engine

The runner engine, also located within the `lib` directory, is responsible for
creating the workspace and executing the code received from the users.

## API

The `api` directory contains the code responsible for generating the executable
that accepts external HTTP requests to execute code. This directory also houses
the VM manager and the server that communicates with the agent to execute the
code.

### model.rs

At the root of the `api` directory, you will find the `model.rs` file, which
contains the structures used by the HTTP server to define the structure of both
requests and responses.

### config.rs

The `config.rs` file holds the definition of data structures and functions
required for loading and manipulating a specific configuration (`LambdoConfig`)
from a YAML file. This configuration is used to parameterize various aspects of
Lambdo, including the Virtual Machine Monitor (VMM), API, agent, and supported
programming languages.

### api (Subdirectory)

Inside the `api` directory, there is also an `api` subdirectory containing the
code for the HTTP server. In `mod.rs`, the `/run` route is defined, which
launches VMs using the `LambdoApiService` service found in `service.rs`.

### vm_manager

The `vm_manager` directory contains all the low-level logic for communicating
with the VM. In the `mod.rs` file, you will find functions for launching the
VMs. Additionally, the `grpc_server.rs` file houses the gRPC server where agents
from the VMs register upon VM startup. This server manages the state of all the
VMs.

#### net.rs

The `net.rs` file is responsible for configuring the network layer of the VMs,
assigning them IP addresses and network interfaces.

## Initramfs

The `initramfs` directory encompasses the Command Line Interface (CLI) tool that
enables the building of a valid initramfs from a Docker image. This initramfs
includes the binary of the agent, its configuration, and an `init` file.

### Fetching Docker Images

The `httpclient.rs` file contains the logic required to make HTTP requests. This
is subsequently utilized in `registry.rs` to fetch the layers of an image from
the Docker Hub.

### image.rs

The `image.rs` file encompasses all the code necessary for building an initramfs
that can be utilized by Lambdo.

## Lumper

Lumper is the Virtual Machine Monitor (VMM) utilized by Lambdo to launch and
manage virtual machines (VMs). It plays a crucial role in the virtualization
layer of the system, providing the necessary functionalities to ensure that VMs
are run efficiently and securely.

## Shared

The `shared` directory is a central hub for elements that are utilized across
various other modules in the project. It serves as a common ground to store
reusable code, configurations, and resources, ensuring consistency and reducing
redundancy throughout the application.
Binary file added public/images/architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading