Merge pull request #12 from faast-rt/feature/docs-advanced

feature: docs advanced

pages/docs/_meta.json

@@ -5,5 +5,6 @@
   },
   "index": "Introduction",
   "getting-started": "Getting Started",
-  "user-guide": "User Guide"
+  "user-guide": "User Guide",
+  "advanced": "Advanced"
 }

pages/docs/advanced/_meta.json

@@ -0,0 +1,5 @@
+{
+  "project-structure": "Project structure",
+  "how-it-works": "How it works ?",
+  "getting-involved": "Getting Involved"
+}

pages/docs/advanced/getting-involved.mdx

@@ -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).

pages/docs/advanced/how-it-works.mdx

@@ -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.

pages/docs/advanced/project-structure.mdx

@@ -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.