Restyling v1

docs/computing/persistent.md → 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.
+TODO: Document Instance VMs

docs/computing/runtimes/existing.md → 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)
 

docs/computing/runtimes/index.md → 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.

docs/computing/volumes/immutable.md → 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:

docs/computing/volumes/persistent.md → 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.

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);
+}

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

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/