Merge pull request #9 from faast-rt/feature/add-getting-started

feat: add getting started

package.json

@@ -13,8 +13,8 @@
   "dependencies": {
     "@headlessui/react": "^1.7.17",
     "next": "^13.0.6",
-    "nextra": "latest",
-    "nextra-theme-docs": "latest",
+    "nextra": "^2.13.2",
+    "nextra-theme-docs": "^2.13.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

pages/docs/_meta.json

@@ -1,8 +1,9 @@
 {
-  "-- Getting Started --": {
+  "-- Quickstart --": {
     "type": "separator",
-    "title": "Getting Started"
+    "title": "Quickstart"
   },
   "index": "Introduction",
+  "getting-started": "Getting Started",
   "user-guide": "User Guide"
 }

pages/docs/getting-started/_meta.json

@@ -0,0 +1,5 @@
+{
+  "installation": "Installation",
+  "configuration": "Configuration",
+  "example-node": "Example: Node"
+}

pages/docs/getting-started/configuration.mdx

@@ -0,0 +1,106 @@
+---
+title: 'Configuration'
+description: 'In this section, we will go through the configuration of Faast.'
+---
+
+import { Callout } from 'nextra/components';
+
+# Configuration
+
+In this section, we will go through the configuration of Faast.
+
+<Callout type="info">
+  Please note that the following configuration is just an example and you should
+  adjust it to your needs.
+</Callout>
+
+```yaml copy filename="config.yaml"
+apiVersion: lambdo.io/v1alpha1
+kind: Config
+api:
+  # The host on which the API server will listen
+  web_host: 0.0.0.0
+  # The port on which the API server will listen
+  web_port: 3000
+  # The host on which the gRPC server will listen
+  grpc_host: 0.0.0.0
+  # The port on which the gRPC server will listen
+  gprc_port: 50051
+  # Bridge name
+  bridge: lambdo0
+  # The IP address of the bridge
+  ip: 10.0.50.0/8
+vmm:
+  # The kernel path to use for the vmm
+  kernel: /var/lib/lambdo/kernel/vmlinux.bin
+agent: # NOT IMPLEMENTED
+  # The path to the agent binary
+  path: /usr/local/bin/lambdo-agent
+  # The path to the agent configuration file
+  config: /etc/lambdo/agent.yaml
+languages:
+  # The name of the language runtime
+  - name: NODE
+    # The version of the node runtime
+    version: 12
+    # The initramfs to use for the runtime
+    initramfs: /var/lib/lambdo/initramfs/node-12.img
+    # The steps to run the code
+    steps:
+      - name: Run the code
+        command: /usr/local/bin/node {{filename}}
+        # The output configuration
+        output:
+          # Whether to enable the output
+          enabled: true
+          # Whether to enable debug output (useful for build steps)
+          debug: false
+```
+
+## API Configuration
+
+The provided configuration file is structured to define various operational
+parameters for Faast. Here's an insightful breakdown of the configuration
+
+### Web Host and Port
+
+`web_host: 0.0.0.0` and `web_port: 3000` specify the host IP and port for the
+API server, enabling it to listen for incoming HTTP requests on all available
+network interfaces at port 3000.
+
+### gRPC Host and Port
+
+`grpc_host: 0.0.0.0` and `gprc_port: 50051` set the host IP and port for the
+gRPC server, facilitating it to listen for gRPC requests on all available
+network interfaces at port 50051.
+
+<Callout type="warning" emoji="⚠️">
+  You should not change the gRPC port unless you know what you are doing.
+</Callout>
+
+### Bridge Configuration
+
+`bridge: lambdo0` and `ip: 10.0.50.0/8` designate the name and IP address for
+the network bridge, which is instrumental in network communications within the
+Faast ecosystem.
+
+<Callout type="warning" emoji="⚠️">
+  You should not change the bridge name and IP address unless you know what you
+  are doing.
+</Callout>
+
+## VMM (Virtual Machine Monitor) Configuration
+
+`kernel: /var/lib/lambdo/kernel/vmlinux.bin` stipulates the path to the Linux
+kernel binary that will be utilized by the VMM.
+
+## Language Runtime Configuration
+
+The configuration for a Node.js runtime is specified with a name `name: NODE`,
+version `version: 12`, and the path to the respective initramfs
+`initramfs: /var/lib/lambdo/initramfs/node-12.img`.
+
+<Callout type="info">
+  If you need more information about the configuration, please refer to the
+  configuration reference.
+</Callout>

pages/docs/getting-started/example-node.mdx

@@ -0,0 +1,83 @@
+---
+title: 'Example: Node'
+description:
+  'This example demonstrates how to deploy a simple Node.js executor on Faast'
+---
+
+import { Steps } from 'nextra/components';
+
+# Example: Node
+
+This example demonstrates how to deploy a simple Node.js executor on Faast using
+Docker Compose. We have provided an example folder on GitHub, containing the
+necessary initramfs and configuration file to work seamlessly with Docker
+Compose.
+
+## A few explanations
+
+In the interest of simplifying the initial setup and demonstration, we have
+pre-compiled the necessary components and included them in the example folder
+available on GitHub.
+
+- The provided initramfs has been built with essential elements already
+  incorporated. It includes an agent responsible for facilitating the
+  communication between the VM and the API via GRPC. Additionally, it comprises
+  the Node.js SDK, enabling the immediate deployment and execution of Node.js
+  functions.
+
+- A configuration file for the Lambdo component is also provided, pre-set with
+  the parameters needed for interfacing with the API. This pre-configuration
+  accelerates the setup process, allowing you to dive directly into deploying
+  and testing your functions.
+
+This pre-configured setup is designed to lower the entry barrier, offering a
+straightforward way to explore Faast's functionality, especially for those new
+to the system or eager to quickly test a Node.js function deployment.
+
+## Let's run it
+
+### Clone the lambdo repository
+
+You can clone the `lambdo` repository from GitHub using the following command:
+
+```bash copy filename="bash"
+git clone https://github.com/faast-rt/lambdo
+cd lambdo
+```
+
+### Start lambdo using Docker Compose
+
+You can start lambdo using Docker Compose using the following command:
+
+```bash copy filename="bash"
+docker compose up
+```
+
+### Execute your Node.js code
+
+Lambdo will now expose an HTTP endpoint on port 3000. You can send a POST
+request to `/run` in order to execute your Node.js code.
+
+The following example uses `curl`:
+
+```bash copy filename="bash"
+curl --location 'http://127.0.0.1:3000/run' \
+  --header 'Content-Type: application/json' \
+  --data '{
+      "language": "NODE",
+      "version": "1.0.0",
+      "input": "",
+      "code": [{
+          "filename": "main.js",
+          "content": "console.log('\''Hello World!'\'')"
+      }]
+  }'
+```
+
+You should see the following output:
+
+```bash filename="bash"
+{"status":0,"stdout":"Hello World\n","stderr":""}
+```
+
+You are now ready to execute your own Node.js code on Faast!

pages/docs/getting-started/installation.mdx

@@ -0,0 +1,74 @@
+---
+title: Installation
+description: This guide will walk you through the steps to install Faast.
+---
+
+import { Callout } from 'nextra/components';
+
+# Installation
+
+This guide will walk you through the steps to install Faast.
+
+## Prerequisites
+
+- A Linux machine (**x86_64**) with a recent version of the Linux kernel (**>=
+  4.15**).
+- KVM **must** be installed on your machine.
+- A recent version of Docker (>= 18.09) installed on your machine **if you want
+  to use Docker**.
+
+## Get Faast
+
+### Download the docker image (recommended)
+
+You can download the latest docker image of Faast from the Docker Hub:
+
+```bash copy filename="bash"
+docker pull faastrt/lambdo
+```
+
+You can also build the docker image from the source code:
+
+```bash copy filename="bash"
+git clone https://github.com/faast-rt/lambdo
+cd lambdo
+docker build -t faastrt/lambdo .
+```
+
+<Callout type="info">
+  You can skip the rest of this section and go to the next page.
+</Callout>
+
+### Download from the latest release
+
+You can download the latest release of Faast from the
+[releases page](https://github.com/faast-rt/lambdo/releases).
+
+```bash copy filename="bash"
+curl -O https://github.com/faast-rt/lambdo/releases/latest/download/lambdo-x86_64-unknown-linux-musl.tar.gz
+tar xvf lambdo-x86_64-unknown-linux-musl.tar.gz
+```
+
+<Callout type="info">
+  You can skip the rest of this section and go to the next page.
+</Callout>
+
+### Build from source
+
+You can build Faast from the source code.
+
+- You will need to install Rust (via Rustup) and the musl target.
+- You will need to install the `pkg-config libudev-dev protobuf-compiler`
+  package on your system.
+
+```bash copy filename="bash"
+git clone https://github.com/faast-rt/lambdo
+cd lambdo
+cargo build -p api --release --target x86_64-unknown-linux-musl
+```
+
+The binary will be available at `target/x86_64-unknown-linux-musl/release/api`.
+
+<Callout>
+  In the next section, you will see how to configure and run Faast.
+</Callout>

pages/docs/index.mdx

@@ -1,13 +1,60 @@
+---
+title: 'Faast Documentation'
+description:
+  'Welcome to the documentation of Faast, a cutting-edge Function as a Service
+  (FaaS) server designed to maximize efficiency.'
+---
+
+import { Callout } from 'nextra/components';
+
 # Introduction
 
-Welcome to Nextra! This is a basic docs template. You can use it as a starting
-point for your own project :)
+Welcome to the documentation of Faast, a cutting-edge Function as a Service
+(FaaS) server designed to maximize efficiency. Developed in the Rust programming
+language, known for its performance and safety, Faast embodies a remarkable
+blend of robustness and agility, essential in modern serverless architectures.
+
+A unique aspect of Faast is its tailored execution environment. The system
+utilizes an initramfs and a bespoke Linux kernel, each constructed expressly for
+Faast's operational requirements. The initramfs contains a specialized SDK of
+the language in use (e.g., Node) and an agent that facilitates GRPC
+communication between the virtual machine and the API. In contrast, the Linux
+kernel operates with an initramfs and employs the newc compression format,
+optimizing the system's performance.
+
+Through these meticulously engineered components and environments, Faast
+transcends conventional FaaS offerings, providing a high-performance, reliable,
+and extensible platform capable of meeting the demanding needs of contemporary
+serverless computing landscapes.
+
+## Features
+
+- The utilization of a custom initramfs and Linux kernel, along with
+  language-specific SDKs, ensures optimized performance and communication
+  between the VM and the API.
+- Faast dynamically receives and executes function code via API without
+  retaining the function, ensuring lightweight operation and real-time code
+  execution.
+- Faast enables streamlined virtual machine launch and management, enhancing the
+  efficiency of function execution.
+- Faast offers a robust and high-speed platform suitable for high-demand
+  serverless computing scenarios.
+- The use of GRPC for communication between the VM and the API provides a
+  modern, protocol-buffer based method for ensuring efficient, robust, and
+  secure inter-component communication.
+
+## License
+
+Distributed under the Apache 2.0 License. See
+[LICENSE](https://github.com/faast-rt/lambdo/blob/main/LICENSE) for more
+information.
 
-## What is Nextra?
+## Authors
 
-A **simple**, **powerful** and **flexible** site generation framework with
-everything you love from Next.js.
+This project was initially developed by the Polytech DO teams (thanks to the
+help of Samuel Ortiz) in April 2023.
 
-## Documentation
+## About the Project
 
-The documentation is available at [https://nextra.site](https://nextra.site).
+For more information about the project, please visit our
+[GitHub organization](https://github.com/faast-rt).