Improve documentation for contributors

README.md

@@ -13,32 +13,111 @@ Writing programs in Python using ASGI compatible frameworks (
 [Django](https://docs.djangoproject.com/en/3.0/topics/async/),
 ...) allows developers to use advanced functionalities not yet available for other languages.
 
-## 1. Install Aleph-VM from packages
+# Production install for Aleph-VM
+## Installation from packages
 
-Install Aleph-VM to run an Aleph.im Compute Resource Node easily from official pre-built packages.
 
-See the official user doc https://docs.aleph.im/nodes/compute/
+Head over to the  official user doc https://docs.aleph.im/nodes/compute/ on how to run an Aleph.im Compute Resource
+Node
 
 ## 2. Install Aleph-VM from source
 
-For development and testing, install Aleph-VM from source.
+This method is not recommended, except for development and testing.
+Read the installation document for the various components and the developer documentation. 
 
 1. Install the [VM-Connector](./vm_connector/README.md)
 2. Install the [VM-Supervisor](src/aleph/vm/orchestrator/README.md).
 3. Install and configure a reverse-proxy such as [Caddy](./CONFIGURE_CADDY.md)
 
-## 3. Create and run an Aleph Program 
+## Create and run an Aleph Program 
 
 Have a look at [tutorials/README.md](tutorials/README.md) for a tutorial on how to program VMs
 as a user.
 
 The rest of this document focuses on how to run an Aleph-VM node that hosts and executes the programs. 
 
-## 4. Architecture
+# Developer Setup
+
+Due to aleph-vm’s deep integration with the Linux system, it must be run with root privileges and configured
+specifically for Linux. **It is strongly recommended** to deploy aleph-vm on a dedicated machine or a cloud-based server
+to ensure security and stability.
+
+> **Note**: aleph-vm does not run on macOS or Windows, including for testing purposes.
+
+### Recommended Development Environment
+
+A typical setup for developing aleph-vm involves:
+
+1. Cloning the repository on your local machine for code editing.
+2. Setting up a remote Linux server for deployment and testing.
+
+You can synchronize changes to the remote server using tools like `rsync` or PyCharm’s Remote Interpreter feature.
+
+## Remote Development Deployment
+
+To deploy aleph-vm for development on a remote server, we start with the Debian package as it includes essential binaries like `firecracker` and `sevctl`, system
+   configuration, and dependencies.
+
+1. **Run the vm-connector.**
+
+The vm-connector need to run for aleph-vm to works, even when running py.test.
+
+Unless your focus is developing the VM-Connector, using the Docker image is easier.
+   See the [VM-Connector README](./vm_connector/README.md) for more details.
+
+   ```shell
+   docker run -d -p 127.0.0.1:4021:4021/tcp --restart=always --name vm-connector alephim/vm-connector:alpha
+   ```
+
+2. **Install the Debian Package**
+   Replace `1.2.0` with the latest release version.
+
+   **On Debian 12 (Bookworm)**:
+   ```shell
+   wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/1.2.0/aleph-vm.debian-12.deb
+   sudo apt install /opt/aleph-vm.debian-12.deb
+   ```
+
+   **On Ubuntu 22.04 (Jammy Jellyfish)**:
+   ```shell
+   sudo wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/1.2.0/aleph-vm.ubuntu-22.04.deb
+   sudo apt install /opt/aleph-vm.ubuntu-22.04.deb
+   ```
+
+   **On Ubuntu 24.04 (Noble Numbat)**:
+   ```shell
+   sudo wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/1.2.0/aleph-vm.ubuntu-24.04.deb
+   sudo apt install /opt/aleph-vm.ubuntu-24.04.deb
+   ```
+
+3. **Disable Systemd Service**  
+   To prevent conflicts, deactivate the system version of aleph-vm by disabling its `systemd` service.
+
+   ```shell
+   sudo systemctl disable aleph-vm-supervisor.service
+   ```
+
+4. **Clone the Repository and Set Up a Virtual Environment**
+    - Clone the aleph-vm repository to your development environment.
+    - Create a virtual environment to manage dependencies.
+
+   Inside the virtual environment, run:
+
+   ```shell
+   pip install -e .
+   ```
+
+   This installs aleph-vm in "editable" mode within the virtual environment, allowing you to use the `aleph-vm` command
+   directly during development.
+
+## Testing
+See [Testinc doc](./TESTING.md)
+
+# Architecture
 
 ![Aleph im VM - Details](https://user-images.githubusercontent.com/404665/127126908-3225a633-2c36-4129-8766-9810f2fcd7d6.png)
 
-### VM Supervisor
+### VM Supervisor (also called Orchestrator)
 
 Actually runs the programs in a secure environment on virtualization enabled systems. 
 

TESTING.md

@@ -1,6 +1,6 @@
 # Testing aleph-vm
 
-This procedure describes how to run tests on a local system.
+This procedure describes how to run tests on a dev system. See the dev setup section of the README first.
 
 Tests also run on GitHub Actions via [the following workflow](./.github/workflows/test-on-droplets-matrix.yml).
 

src/aleph/vm/models.py

@@ -145,6 +145,9 @@
         else:
             return True
 
+    def __repr__(self):
+        return f"<VMExecution {type(self.vm).__name__} {self.vm_hash} {self.times.started_at}>"
+
     def __init__(
         self,
         vm_hash: ItemHash,

src/aleph/vm/pool.py

@@ -86,7 +86,7 @@ def teardown(self) -> None:
     async def create_a_vm(
         self, vm_hash: ItemHash, message: ExecutableContent, original: ExecutableContent, persistent: bool
     ) -> VmExecution:
-        """Create a new Aleph Firecracker VM from an Aleph function message."""
+        """Create a new VM from an Aleph function or instance message."""
         async with self.creation_lock:
             # Check if an execution is already present for this VM, then return it.
             # Do not `await` in this section.

tests/supervisor/test_authentication.py

@@ -243,7 +243,7 @@ async def view(request, authenticated_sender):
 async def generate_sol_signer_and_signed_headers_for_operation(
     patch_datetime_now, operation_payload: dict
 ) -> tuple[solathon.Keypair, dict]:
-    """Generate a temporary eth_account for testing and sign the operation with it"""
+    """Generate a temporary sol account for testing and sign the operation with it"""
 
     kp = solathon.Keypair()
     key = jwk.JWK.generate(

tests/supervisor/test_instance.py

@@ -63,8 +63,8 @@
     # Ensure that the settings are correct and required files present.
     settings.setup()
     settings.check()
-    if not settings.FAKE_DATA_RUNTIME.exists():
-        pytest.xfail("Test Runtime not setup. run `cd runtimes/aleph-debian-12-python && sudo ./create_disk_image.sh`")
+    if not settings.FAKE_INSTANCE_BASE.exists():
+        pytest.xfail("Test Runtime not setup. run `cd runtimes/instance-rootfs && sudo ./create-debian-12-disk.sh`")
 
     # The database is required for the metrics and is currently not optional.
     engine = metrics.setup_engine()