diff --git a/README.md b/README.md index 783f02a09..61f9271cc 100644 --- a/README.md +++ b/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. diff --git a/TESTING.md b/TESTING.md index 7adbae0c6..1c6e05bcb 100644 --- a/TESTING.md +++ b/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). diff --git a/src/aleph/vm/models.py b/src/aleph/vm/models.py index 35de4076d..9aee9320a 100644 --- a/src/aleph/vm/models.py +++ b/src/aleph/vm/models.py @@ -145,6 +145,9 @@ def has_resources(self) -> bool: else: return True + def __repr__(self): + return f"" + def __init__( self, vm_hash: ItemHash, diff --git a/src/aleph/vm/pool.py b/src/aleph/vm/pool.py index 025bfe45c..58a3e6fae 100644 --- a/src/aleph/vm/pool.py +++ b/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. diff --git a/tests/supervisor/test_authentication.py b/tests/supervisor/test_authentication.py index 6fb3d0811..73769c97c 100644 --- a/tests/supervisor/test_authentication.py +++ b/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( diff --git a/tests/supervisor/test_instance.py b/tests/supervisor/test_instance.py index 6a3ffa509..1319c99c4 100644 --- a/tests/supervisor/test_instance.py +++ b/tests/supervisor/test_instance.py @@ -63,8 +63,8 @@ async def test_create_instance(): # 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()