diff --git a/docs/computing/custom domain/Adding a Custom Domain.md b/docs/VMs/Custom Domains/Adding a Custom Domain.md similarity index 100% rename from docs/computing/custom domain/Adding a Custom Domain.md rename to docs/VMs/Custom Domains/Adding a Custom Domain.md diff --git a/docs/computing/persistent.md b/docs/VMs/index.md similarity index 55% rename from docs/computing/persistent.md rename to docs/VMs/index.md index a7050fe..b1b7f73 100644 --- a/docs/computing/persistent.md +++ b/docs/VMs/index.md @@ -1,13 +1,37 @@ -# Persistent Execution +# Computing on Aleph.im -## Introduction +Aleph.im offers a decentralized computing framework that allows users to run +programs on the network. This is done by creating a virtual machine (VM) that +executes the program. -The aleph.im network can run programs in two different manners: +## Overview of VMs -* [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. +There are several types of VMs available on the network: + +- [On-demand VM](#on-demand-execution) +- [Persistent VM](#persistent-execution) +- [Instance VM](#instance-vms) + +An [On-demand VM](#on-demand-execution) is created on a [Compute Resource Node](../nodes/Compute_(CRN)/index.md) +(CRN) and is destroyed once the program has finished executing. This is great +for programs that are responding to user requests or API calls (using ASGI) and can shutdown +after processing the event. They are also cheaper to run as they only require +one tenth of the $ALEPH tokens to hold, compared to a [Persistent VM](#persistent-execution). + +A [Persistent VM](#persistent-execution) can be used to run programs that cannot afford to stop or need +to handle incoming connections such as polling data from a websocket or AMQP API. + +Instances are similar to Persistent VMs, but are specifically designed to run with +a SSH key supplied by the user. This allows the user to connect to the VM and +interact with it directly. They do not rely on code execution, but rather on +the user's ability to connect to the VM and run commands on it. +They cost as much as Persistent VMs. + +## On-demand Execution + +On how to deploy a simple Python microVM, see our [Python microVM guide](../guides/python/getting_started.md) + +## Persistent Execution 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. @@ -17,7 +41,7 @@ CRN would the current one go offline. > ⚠️ Automatic data migration across hosts in case such events happen is not available yet. -## Message Specification +### Message Specification The execution model of a program is defined in the field `message.content.on` of messages of type `PROGRAM` and is non exclusive. The same program can therefore be available as both persistent instance and on demand at the same time. @@ -39,7 +63,7 @@ message = { } ``` -## Prerequisites +### Prerequisites Before you begin this tutorial, ensure that you have the following: @@ -73,7 +97,7 @@ cd ./src/ uvicorn main:app --reload ``` -## Step 2: Run a program in a persistent manner +### Step 2: Run a program in a persistent manner To run the program in a persistent manner on the aleph.im network, use: @@ -87,10 +111,10 @@ You can stop the execution of the program using: aleph unpersist $MESSAGE_ID ``` -## Find your program +### Find your program TODO: Locate the CRN where your program is running. -## Conclusion +## Instance VMs -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 +TODO: Document Instance VMs \ No newline at end of file diff --git a/docs/computing/runtimes/custom.md b/docs/VMs/runtimes/custom.md similarity index 100% rename from docs/computing/runtimes/custom.md rename to docs/VMs/runtimes/custom.md diff --git a/docs/computing/runtimes/existing.md b/docs/VMs/runtimes/existing.md similarity index 94% rename from docs/computing/runtimes/existing.md rename to docs/VMs/runtimes/existing.md index 3794b34..9c90094 100644 --- a/docs/computing/runtimes/existing.md +++ b/docs/VMs/runtimes/existing.md @@ -9,7 +9,7 @@ This runtime is built with software available in the distribution, including Pyt 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). +especially useful when using [on-demand execution](../index.md#on-demand-execution). [//]: # (Not available yet) diff --git a/docs/computing/runtimes/index.md b/docs/VMs/runtimes/index.md similarity index 82% rename from docs/computing/runtimes/index.md rename to docs/VMs/runtimes/index.md index 9575d68..039a524 100644 --- a/docs/computing/runtimes/index.md +++ b/docs/VMs/runtimes/index.md @@ -14,7 +14,7 @@ custom runtimes, and use any available runtime on the network for your program. ## Init process -[On-demand Execution](../on_demand.md) relies on a custom [Linux init](https://en.wikipedia.org/wiki/Init) process, +[On-demand Execution](../index.md#on-demand-execution) 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) @@ -23,6 +23,6 @@ and [init1.py](https://raw.githubusercontent.com/aleph-im/aleph-vm/main/runtimes 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 +[Persistent Execution](../index.md#persistent-execution) 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/computing/volumes/immutable.md b/docs/VMs/volumes/immutable.md similarity index 92% rename from docs/computing/volumes/immutable.md rename to docs/VMs/volumes/immutable.md index 5bdf466..e89a2fe 100644 --- a/docs/computing/volumes/immutable.md +++ b/docs/VMs/volumes/immutable.md @@ -2,7 +2,7 @@ An immutable volume is a file containing a [Squashfs filesystem](https://www.kernel.org/doc/html/latest/filesystems/squashfs.html) that can be mounted read-only -inside the virtual machine running programs in [on-demand](../on_demand.md) or [persistent](../persistent.md) execution +inside the virtual machine running programs in [on-demand](../index.md#on-demand-execution) or [persistent](../index.md#persistent-execution) execution modes. This type of volume is typically used to provide additional libraries or data to the program. Immutable volumes have the following properties: diff --git a/docs/computing/volumes/persistent.md b/docs/VMs/volumes/persistent.md similarity index 90% rename from docs/computing/volumes/persistent.md rename to docs/VMs/volumes/persistent.md index bcb1446..aaa5437 100644 --- a/docs/computing/volumes/persistent.md +++ b/docs/VMs/volumes/persistent.md @@ -1,7 +1,7 @@ ## Persistent Volumes Persistent volumes are logical block disks that are attached to virtual machines running programs -in [on-demand](../on_demand.md) or [persistent](../persistent.md) execution modes. They are typically used to store +in [on-demand](../index.md#on-demand-execution) or [persistent](../index.md#persistent-execution) execution modes. They are typically used to store mutable data such as databases and persist data. Currently, persistent volumes are only stored on the [Compute Resource Node](../../nodes/Compute_(CRN)/index.md) (CRN) that is executing the program. Automatic backups and restoration in case of failure of the CRN is a feature that is planned to be added in the future, and is currently left to the user. diff --git a/docs/assets/images/square-logo-color.png b/docs/assets/images/square-logo-color.png new file mode 100755 index 0000000..cc3cf26 Binary files /dev/null and b/docs/assets/images/square-logo-color.png differ diff --git a/docs/assets/stylesheets/aleph-branding.css b/docs/assets/stylesheets/aleph-branding.css new file mode 100644 index 0000000..06ca2be --- /dev/null +++ b/docs/assets/stylesheets/aleph-branding.css @@ -0,0 +1,129 @@ +[data-md-color-scheme="default"] { + --md-primary-fg-color: #029AFF; /* Primary color */ + --color-text: #333333; /* Text color for light mode */ + --color-background: #f7f7f7; /* Background color for light mode */ + --color-border: #eaecef; /* Border color for light mode */ + --color-button-background: #f7f7f7; /* Button background for light mode */ + --md-default-bg-color: #ffffff; /* Footer background for light mode */ +} + +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #029AFF; /* Primary color */ + --color-text: #dddddd; /* Text color for dark mode */ + --color-background: #424242; /* Background color for dark mode */ + --color-border: #616161; /* Border color for dark mode */ + --color-button-background: #5a5a5a; /* Button background for dark mode */ + --md-default-bg-color: #333333; /* Footer background for dark mode */ +} + +/* Base styles */ +body { + font-family: 'Source Sans Pro', sans-serif; + color: var(--color-text); + background-color: var(--color-background); + line-height: 1.6; +} + +/* Header styles */ +.header, .md-header { + background-color: var(--md-default-bg-color); + color: var(--color-text); + border-bottom: 1px solid var(--color-border); +} + +.md-tabs { + background-color: var(--md-default-bg-color); + color: var(--color-text); + border-bottom: 1px solid var(--color-border); +} + +.md-tabs__link { + font-weight: bold; +} + +.md-tabs__link--active { + font-weight: bolder; +} + +/* Navigation menu styles */ +.md-sidebar--primary, .md-nav--primary { + padding-top: 24px; + background-color: var(--color-background); + font-size: large; + color: var(--color-text); +} + +.md-sidebar--secondary, .md-nav--secondary { + padding-top: 24px; + background-color: var(--color-background); +} + +.md-sidebar--secondary, .md-nav--secondary label { + font-size: large; +} + +.md-nav__source { + color: var(--color-text); + background-color: var(--color-background); +} + +.md-nav__link { + color: var(--color-text); /* Default state */ + text-decoration: none; +} + +.md-nav__link:hover { + color: var(--md-primary-fg-color) !important; +} + +.md-nav__link--active { + color: var(--md-primary-fg-color) !important; + font-weight: bold; +} + +.md-nav a { + margin: 10px; +} + +/* Main content area styles */ +.md-content { + background-color: var(--md-default-bg-color); + padding: 20px; + margin-bottom: 20px; + box-shadow: inset 0 0 10px var(--color-background); +} + +/* Code block styles */ +.md-code, pre code { + background-color: var(--color-background); + border: 1px solid var(--color-border); +} + +/* Typography */ +h1, h2, h3, h4, h5, h6 { + color: var(--color-text); +} + +/* Link styling */ +a:not(.md-nav__link) { + color: var(--md-primary-fg-color); +} + +/* Button styling */ +.md-button, button { + background-color: var(--color-background); /* Light background for buttons */ + color: var(--color-text); + border: 1px solid var(--color-border); + cursor: pointer; +} + +.md-button:hover, button:hover { + background-color: var(--color-background); +} + +/* Footer styles */ +.footer, .md-footer { + background-color: var(--md-default-bg-color); + color: var(--color-text); + border-top: 1px solid var(--color-border); +} diff --git a/docs/computing/on_demand.md b/docs/computing/on_demand.md deleted file mode 100644 index c77b0b6..0000000 --- a/docs/computing/on_demand.md +++ /dev/null @@ -1 +0,0 @@ -# On-demand Execution diff --git a/docs/index.md b/docs/index.md index aa322d4..7f1fcca 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,50 @@ -# Aleph.im Documentation +# Overview Welcome to the Aleph.im documentation. This site will provide you with all the necessary information, resources, and tools to get started with the Aleph.im project. +## What is Aleph.im? + +Aleph.im is an open-source off-chain P2P (peer-to-peer) network. It offers decentralized volumes and blockchain indexing, function execution and VM provisioning, as well as a DID (decentralized identity) framework. +Aleph.im also includes bridges to many major blockchain networks, such as Ethereum (or any EVM-compatible blockchain), Tezos and Solana, to enable smart contracts access to the resources and hosted on the Aleph.im network. + +### The Aleph.im project has the following components: + +* The Aleph peer-to-peer network, comprised of [Compute Resource Nodes or CRNs](nodes/Compute_(CRN)/index.md) and [Core Channel Nodes, or CCNs](nodes/Core_(CCN)/index.md) +* [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs to integrate Aleph.im's decentralized compute and storage solutions into your project +* A [Python CLI tool](https://aleph-client.readthedocs.io/en/latest/) to interact with the Aleph.im network directly from a terminal +* A [web GUI dashboard](https://console.aleph.im/) +* An [Explorer](https://explorer.aleph.im/) + +## The Aleph.im network + +![The Aleph.im network](./network-overview.svg) + +The Aleph.im network is composed of 2 sets of nodes: + +* [CCNs](nodes/Core_(CCN)/index.md), the backbone of the P2P network. They serve as an entry point into the network through an API (similar to a blockchain node's RPC). +* [CRNs](nodes/Compute_(CRN)/index.md), responsible for the actual compute and storage available on Aleph.im. CRNs must be tied manually to a single CCN, and each CCN is incentivized to tie up to 3 CRNs. + +### Messages +In Aleph.im terminology, a "message" is similar to a "transaction" for a blockchain: it is a set of data sent by an end user, propagated through the entire peer-to-peer network. +A message can be generated using either the [python](./libraries/python.md) or [typescript](./libraries/typescript.md) SDKs, or through the [aleph-client](https://aleph-client.readthedocs.io/en/latest/) or the [web dashboard](https://console.aleph.im/). +These messages can contain several different instructions, such as reading or writing [posts](https://aleph-client.readthedocs.io/en/latest/content/posts.html#), [programs/functions](VMs/index.md), or [indexing data](tools/indexer.md) created on external blockchains. + +### Payment +While Aleph is not a blockchain. It uses the ALEPH token hosted on Ethereum to manage users' payments and offer network integrity and workload execution rewards to node operators. Because of this, you must have an EVM-compatible wallet (such as Metamask) provisioned with some ALEPH tokens to write to the network. + +### Example +Let's take the example of a user who wants to run a program on the Aleph.im network: + +1. The user makes sure to have an Ethereum wallet with at least 2000 ALEPH tokens +2. The user writes and sends a message using either the aleph python client, one of the SDKs, or the web dashboard +3. The message arrives at a CCN, which then broadcasts that message to all CCNs in the network +4. The "program" workload scheduled by the user's message gets assigned to one of the CCNs +5. The assigned CCN now assigns that workload onto one of its CRNs +6. The assigned CRN creates a micro-vm executing the user's requested workload. + ## Where to start? -- Read the [Overview](./overview.md) to understand what Aleph.im is and how it works. - Use our [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs. - Follow a [Tutorial to run Python code on aleph.im](guides/python/getting_started.md). - Become part of the network by managing a [Core Channel Node](nodes/Core_(CCN)/index.md) or a [Compute Resource Node](nodes/Compute_(CRN)/index.md). diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index b00c790..0000000 --- a/docs/overview.md +++ /dev/null @@ -1,41 +0,0 @@ -# Overview - -## What is Aleph.im? - -Aleph.im is an open-source off-chain P2P (peer-to-peer) network. It offers decentralized volumes and blockchain indexing, function execution and VM provisioning, as well as a DID (decentralized identity) framework. -Aleph.im also includes bridges to many major blockchain networks, such as Ethereum (or any EVM-compatible blockchain), Tezos and Solana, to enable smart contracts access to the resources and hosted on the Aleph.im network. - -### The Aleph.im project has the following components: - -* The Aleph peer-to-peer network, comprised of [Compute Resource Nodes or CRNs](nodes/Compute_(CRN)/index.md) and [Core Channel Nodes, or CCNs](nodes/Core_(CCN)/index.md) -* [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs to integrate Aleph.im's decentralized compute and storage solutions into your project -* A [Python CLI tool](https://aleph-client.readthedocs.io/en/latest/) to interact with the Aleph.im network directly from a terminal -* A [web GUI dashboard](https://console.aleph.im/) -* An [Explorer](https://explorer.aleph.im/) - -## The Aleph.im network - -![The Aleph.im network](./network-overview.svg) - -The Aleph.im network is composed of 2 sets of nodes: - -* [CCNs](nodes/Core_(CCN)/index.md), the backbone of the P2P network. They serve as an entry point into the network through an API (similar to a blockchain node's RPC). -* [CRNs](nodes/Compute_(CRN)/index.md), responsible for the actual compute and storage available on Aleph.im. CRNs must be tied manually to a single CCN, and each CCN is incentivized to tie up to 3 CRNs. - -### Messages -In Aleph.im terminology, a "message" is similar to a "transaction" for a blockchain: it is a set of data sent by an end user, propagated through the entire peer-to-peer network. -A message can be generated using either the [python](./libraries/python.md) or [typescript](./libraries/typescript.md) SDKs, or through the [aleph-client](https://aleph-client.readthedocs.io/en/latest/) or the [web dashboard](https://console.aleph.im/). -These messages can contain several different instructions, such as reading or writing [posts](https://aleph-client.readthedocs.io/en/latest/content/posts.html#), [programs/functions](./computing/persistent.md), or [indexing data](./frameworks/indexer.md) created on external blockchains. - -### Payment -While Aleph is not a blockchain. It uses the ALEPH token hosted on Ethereum to manage users' payments and offer network integrity and workload execution rewards to node operators. Because of this, you must have an EVM-compatible wallet (such as Metamask) provisioned with some ALEPH tokens to write to the network. - -### Example -Let's take the example of a user who wants to run a program on the Aleph.im network: - -1. The user makes sure to have an Ethereum wallet with at least 2000 ALEPH tokens -2. The user writes and sends a message using either the aleph python client, one of the SDKs, or the web dashboard -3. The message arrives at a CCN, which then broadcasts that message to all CCNs in the network -4. The "program" workload scheduled by the user's message gets assigned to one of the CCNs -5. The assigned CCN now assigns that workload onto one of its CRNs -6. The assigned CRN creates a micro-vm executing the user's requested workload. \ No newline at end of file diff --git a/docs/stylesheets/aleph-branding.css b/docs/stylesheets/aleph-branding.css deleted file mode 100644 index e69de29..0000000 diff --git a/docs/frameworks/indexer.md b/docs/tools/indexer.md similarity index 100% rename from docs/frameworks/indexer.md rename to docs/tools/indexer.md diff --git a/mkdocs.yml b/mkdocs.yml index 2f143e3..38f4f4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,7 @@ site_name: Aleph.im Documentation theme: name: material + logo: assets/images/square-logo-color.png palette: # Palette toggle for light mode @@ -21,6 +22,7 @@ theme: - navigation.tracking - navigation.sections - navigation.path + - navigation.tabs markdown_extensions: - pymdownx.highlight: anchor_linenums: true @@ -38,7 +40,7 @@ extra_javascript: - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js extra_css: - - stylesheets/aleph-branding.css + - assets/stylesheets/aleph-branding.css repo_url: https://github.com/aleph-im/aleph-docs edit_uri: edit/main/docs/