From 705e5ca8fb6c75e4d640d7cf344489d6d911ac77 Mon Sep 17 00:00:00 2001 From: "Andres D. Molins" Date: Tue, 28 Mar 2023 16:27:00 +0200 Subject: [PATCH 1/2] Doc: Runtimes were not documented Co-authored-by: Hugo Herter --- docs/execution/runtimes/existing.md | 28 ++++++++++++ docs/execution/runtimes/index.md | 28 ++++++++++++ docs/execution/runtimes/rebuild.md | 70 +++++++++++++++++++++++++++++ 3 files changed, 126 insertions(+) create mode 100644 docs/execution/runtimes/existing.md create mode 100644 docs/execution/runtimes/index.md create mode 100644 docs/execution/runtimes/rebuild.md diff --git a/docs/execution/runtimes/existing.md b/docs/execution/runtimes/existing.md new file mode 100644 index 0000000..3794b34 --- /dev/null +++ b/docs/execution/runtimes/existing.md @@ -0,0 +1,28 @@ +# Existing Runtimes + +### Official runtime with Debian 11, Python 3.9 and NodeJS 14 + +Aleph.im provides users with a default runtime based on [Debian 11 "bullseye"](https://wiki.debian.org/DebianBullseye), +the current stable version of the Debian project which can +be [found on the Explorer](https://explorer.aleph.im/address/ETH/0x101d8D16372dBf5f1614adaE95Ee5CCE61998Fc9/message/STORE/bd79839bf96e595a06da5ac0b6ba51dea6f7e2591bb913deccded04d831d29f4). +This runtime is built with software available in the distribution, including Python 3.9 and Nodejs 14. + +To optimize performance, this runtime uses a custom [Linux init](https://en.wikipedia.org/wiki/Init) process. This +process is specially designed to quickly launch the right endpoint in response to events such as HTTP requests. This is +especially useful when using [on-demand execution](../on_demand.md). + +[//]: # (Not available yet) + +[//]: # (### Official minimal runtime for binaries (Rust, Go, ...)) + +[//]: # () + +[//]: # (This official minimal runtime is designed to run Linux binaries quickly and efficiently. It is built on a minimal) + +[//]: # (system, and does not include interpreters or virtual machines for popular programming languages. This makes launching) + +[//]: # (binaries fast and efficient.) + +### Third-party runtimes + +Use third-party runtimes available on the network by specifying their `item_hash` when creating your program. diff --git a/docs/execution/runtimes/index.md b/docs/execution/runtimes/index.md new file mode 100644 index 0000000..3ede297 --- /dev/null +++ b/docs/execution/runtimes/index.md @@ -0,0 +1,28 @@ +# Introduction + +A program runtime is an operating system and software stack that enables your program to run on the aleph.im network. + +Runtimes are customized Linux root filesystems that integrate with the Aleph.im infrastructure and provide access to +APIs, as well as quick responses to HTTP requests and other events. + +The project provides official runtimes with all you need for most programs. Additionally, you can build and publish +custom runtimes, and use any available runtime on the network for your program. + +- [Use existing runtimes](./existing.md) +- [Create custom runtimes](./custom.md) + + +## Init process + +[On-demand Execution](../on_demand.md) relies on a custom [Linux init](https://en.wikipedia.org/wiki/Init) process, +optimized to launch the right endpoint in response to events such as HTTP requests. This custom init consists in two +simple programs, +[init0.sh](https://raw.githubusercontent.com/aleph-im/aleph-vm/main/runtimes/aleph-alpine-3.13-python/init0.sh) +and [init1.py](https://raw.githubusercontent.com/aleph-im/aleph-vm/main/runtimes/aleph-alpine-3.13-python/init1.py). + +Use these in your custom runtime by copying them to `/rootfs/sbin/init` and +`/mnt/rootfs/root/init1.py` respectively. + +[Persistent Execution](../persistent.md) may use the same init process, but this is not required. If you do not make use +of the capabilities provided by the Aleph.im ecosystem, using the default of your distribution +(ex: [systemd](https://systemd.io/), [OpenRC](https://github.com/OpenRC/openrc), ...) should work as well. diff --git a/docs/execution/runtimes/rebuild.md b/docs/execution/runtimes/rebuild.md new file mode 100644 index 0000000..fde9ff9 --- /dev/null +++ b/docs/execution/runtimes/rebuild.md @@ -0,0 +1,70 @@ +# Custom Runtimes + +Custom runtimes can be created by customizing the filesystem of Linux distributions or +[entirely from scratch](https://linuxfromscratch.org/lfs/). + +## Base filesystem + +Refer to the installation guide of your distribution for the procedure to obtain a base root filesystem. + +> ⚠️ Only x86-64 is currently supported on the network. Make sure you use build runtimes on that architecture. + +### Debian Bullseye + +```shell +mkdir ./rootfs +debootstrap --arch=amd64 --variant=minbase bullseye ./rootfs http://deb.debian.org/debian/ +``` + +### Ubuntu 22.04 + +```shell +mkdir ./rootfs +debootstrap --arch=amd64 jammy ./rootfs http://archive.ubuntu.com/ubuntu/ +``` + +[//]: # (#### NixOS - TODO) + + +Following the next steps, you will be able to create and customize your own Debian based runtime: + +## 1. Install required dependencies + +First you need to install the required tools to be able to generate you own runtime. + +Using Debian and Ubuntu systems: + +```shell +sudo apt-get install debootstrap chroot mksquashfs +``` + +Using Nix: +```shell +nix-shell -p debootstrap squashfsTools +``` + +## 2. Obtain the build scripts + +Download the files `create_disk_image.sh`, `init0.sh` and `init1.py` from the +[official runtime](existing.md#official-runtime-with-debian-11-python-39-and-nodejs-14): + +[https://github.com/aleph-im/aleph-vm/tree/main/runtimes/aleph-debian-11-python](https://github.com/aleph-im/aleph-vm/tree/main/runtimes/aleph-debian-11-python) + +Customize these files to suit your needs. + +## 3. Build a new runtime + +Running the script `create_disk_image.sh` as root will create a file named `rootfs.squashfs`: + +```shell +sudo ./create_disk_image.sh +``` + +## 4. Publish the runtime on Aleph.im + +```shell +aleph file pin ./rootfs.squashfs +``` + +This command will provide you with the `item_hash` of the custom runtime, +that you can then use when creating the program. From 96b4344cb280e270265e09257811e46d34cfee46 Mon Sep 17 00:00:00 2001 From: Hugo Herter Date: Tue, 11 Apr 2023 15:14:41 +0200 Subject: [PATCH 2/2] Rename "Aleph" -> "aleph.im" --- docs/execution/persistent.md | 8 ++++---- docs/execution/runtimes/index.md | 4 ++-- docs/execution/runtimes/rebuild.md | 4 ++-- docs/execution/volumes/immutable.md | 4 ++-- docs/overview.md | 4 ++-- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/execution/persistent.md b/docs/execution/persistent.md index a23cae0..a7050fe 100644 --- a/docs/execution/persistent.md +++ b/docs/execution/persistent.md @@ -2,14 +2,14 @@ ## Introduction -The Aleph.im network can run programs in two different manners: +The aleph.im network can run programs in two different manners: * [on-demand execution](on_demand.md) runs programs only when needed, saving on resources. This is great to run programs that are responding to user requests or API calls and can shutdown after processing the event. * __persistent execution__ runs programs continuously. These are always running and great to run programs that cannot afford to stop or need to handle incoming connections such as polling data from a websocket or AMQP API. -When a program is created with persistent execution enabled, the Aleph.im scheduler will find a Compute Resource Node +When a program is created with persistent execution enabled, the aleph.im scheduler will find a Compute Resource Node (CRN) with enough resources to run the program and schedule the program to start on that node. Persistent programs are designed to always run exactly once, and the scheduler will reallocate the program on another @@ -75,7 +75,7 @@ uvicorn main:app --reload ## Step 2: Run a program in a persistent manner -To run the program in a persistent manner on the Aleph.im network, use: +To run the program in a persistent manner on the aleph.im network, use: ```shell aleph program upload --persistent ./src/ main:app @@ -93,4 +93,4 @@ TODO: Locate the CRN where your program is running. ## Conclusion -In this tutorial, you learned how to create and deploy persistent Virtual Machines on the Aleph.im network. You should now have a better understanding of how to use Aleph.im for distributed computing. \ No newline at end of file +In this tutorial, you learned how to create and deploy persistent Virtual Machines on the aleph.im network. You should now have a better understanding of how to use aleph.im for distributed computing. \ No newline at end of file diff --git a/docs/execution/runtimes/index.md b/docs/execution/runtimes/index.md index 3ede297..9575d68 100644 --- a/docs/execution/runtimes/index.md +++ b/docs/execution/runtimes/index.md @@ -2,7 +2,7 @@ A program runtime is an operating system and software stack that enables your program to run on the aleph.im network. -Runtimes are customized Linux root filesystems that integrate with the Aleph.im infrastructure and provide access to +Runtimes are customized Linux root filesystems that integrate with the aleph.im infrastructure and provide access to APIs, as well as quick responses to HTTP requests and other events. The project provides official runtimes with all you need for most programs. Additionally, you can build and publish @@ -24,5 +24,5 @@ Use these in your custom runtime by copying them to `/rootfs/sbin/init` and `/mnt/rootfs/root/init1.py` respectively. [Persistent Execution](../persistent.md) may use the same init process, but this is not required. If you do not make use -of the capabilities provided by the Aleph.im ecosystem, using the default of your distribution +of the capabilities provided by the aleph.im ecosystem, using the default of your distribution (ex: [systemd](https://systemd.io/), [OpenRC](https://github.com/OpenRC/openrc), ...) should work as well. diff --git a/docs/execution/runtimes/rebuild.md b/docs/execution/runtimes/rebuild.md index fde9ff9..f899ab1 100644 --- a/docs/execution/runtimes/rebuild.md +++ b/docs/execution/runtimes/rebuild.md @@ -7,7 +7,7 @@ Custom runtimes can be created by customizing the filesystem of Linux distributi Refer to the installation guide of your distribution for the procedure to obtain a base root filesystem. -> ⚠️ Only x86-64 is currently supported on the network. Make sure you use build runtimes on that architecture. +> ⚠️ Only 64-bit Intel/AMD processors (x86_64) are supported on the network at the moment . Make sure you build runtimes on that architecture. ### Debian Bullseye @@ -60,7 +60,7 @@ Running the script `create_disk_image.sh` as root will create a file named `root sudo ./create_disk_image.sh ``` -## 4. Publish the runtime on Aleph.im +## 4. Publish the runtime on aleph.im ```shell aleph file pin ./rootfs.squashfs diff --git a/docs/execution/volumes/immutable.md b/docs/execution/volumes/immutable.md index 244f32b..5bdf466 100644 --- a/docs/execution/volumes/immutable.md +++ b/docs/execution/volumes/immutable.md @@ -24,7 +24,7 @@ Additional data can be provided to a program by bundling it in an immutable volu mksquashfs ./custom-data data.squashfs ``` -### 2. Publish the file on Aleph +### 2. Publish the file on aleph.im ```shell aleph file pin ./data.squashfs @@ -51,7 +51,7 @@ pip3 install -t ./packages -r ./requirements.txt mksquashfs ./packages packages.squashfs ``` -### 3. Publish the file on Aleph +### 3. Publish the file on aleph.im ```shell aleph file pin ./packages.squashfs diff --git a/docs/overview.md b/docs/overview.md index 6cacd5d..248f024 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,7 +1,7 @@ # Overview -## What is Aleph? +## What is aleph.im? -Aleph is an open-source off-chain P2P (peer-to-peer) network featuring a decentralized database (inc. file storage), +Aleph.im is an open-source off-chain P2P (peer-to-peer) network featuring a decentralized database (inc. file storage), computing, and a DID framework. Aleph allows your blockchain-enabled app (dApp) to securely access trusted off-chain data or computation through cross-chain connectivity and our client libraries.