Build a Python microVM
This tutorial will guide you through the steps of building a Python microVM to run on the aleph.im network. We will build a simple HTTP server and add features as we go.
ℹ This tutorial uses the aleph.im command line interface.
To complete this tutorial, you will use the
aleph command from
fastapi framework to create a
simple API and the
uvicorn server to test your program on your desktop before uploading it on
First, you need a recent version of Python and pip, preferably running on Debian 11 or Ubuntu 20.04.
Understanding aleph.im programs
Aleph.im programs are applications running on the aleph.im network. Each program defines the application to be executed, data to use, computing requirements (number of CPUs, amount of RAM) and many more parameters.
Each program is instantiated as a virtual machine running on a Compute Resource Node (CRN). Virtual machines are emulated computer systems with dedicated resources that run isolated from each other. Aleph.im Virtual Machines (VMs) are based on Linux.
We support two types of VMs: microVMs and persistent VMs. MicroVMs boot extremely fast and can be launched on demand. They are perfect for lightweight applications that only run once in a while. Persistent VMs on the other hand are constantly running, making them suited to run larger applications.
The base of each VM is a Linux root filesystem named runtime and configured to run programs on the aleph.im platform.
Aleph.im provides a supported runtime to launch programs written in Python or binaries.
- Python programs must support the ASGI interface, described in the example below.
- Binaries must listen for HTTP requests on port 8080
The runtime currently supported by aleph.im is aleph-debian-11-python.
VMs can be extended by specifying additional volumes that will be mounted in the system.
Ephemeral volumes provide temporary disk storage to a VM during its execution without requiring more memory.
Host persistent volumes are persisted on the VM execution node, but may be garbage collected by the node without warning.
Store persistent volumes (not available yet) are persisted on the aleph.im network. New VMs will try to use the latest version of this volume, with no guarantee against conflicts.
Write a Python program
To create the first program, open your favourite code editor and create a directory named
my-program, containing a file named
Then write the following code in the file:
That's it for your first program.
This code comes from the FastAPI tutorial. Have a look at it for a better understanding of what it does and how it works.
Test it locally
Before uploading your program on aleph.im, let's test it on your machine.
Test your program locally using uvicorn, an ASGI server:
If you are on macOS you can use vagrant to emulate a Linux system:
Then go to your working repository and launch:
--reload option will automatically reload your app when the code changes.
ℹ️ If you are running this on a different system than your desktop, specify the IP address of that system using
uvicorn main:app --reload --host 22.214.171.124, where
126.96.36.199is the IP address of the system. Then open your browser on http://188.8.131.52:8000 instead.
ℹ Installing uvicorn should add the
uvicorncommand to your shell. If it does not, use
python -m uvicornto run it.
Upload your program on aleph.im
After installing aleph-client, you should have access to the
Let's upload our program.
aleph program CODE_DIR ENTRYPOINT command will package the
CODE_DIR code directory and configure the program
to run the
For Python programs,
ENTRYPOINT can be the module path to an ASGI application.
This command will upload our Python code and configure
main:app as the ASGI application.
Press Enter at the following prompt to use the default runtime:
Press Enter again to skip adding extra volumes to your program:
You should then get a response similar to the following:
Your program has been uploaded on aleph.im . Available on: https://aleph.sh/vm/1d3842fc4257c0fd4f9c7d5c55bba16264de8d44f47265a14f8f6eb4d542dda2 https://du4ef7cck7ap2t44pvoflo5bmjsn5dke6rzglikpr5xljvkc3wra.aleph.sh Visualise on: https://explorer.aleph.im/address/ETH/0x101d8D16372dBf5f1614adaE95Ee5CCE61998Fc9/message/PROGRAM/1d3842fc4257c0fd4f9c7d5c55bba16264de8d44f47265a14f8f6eb4d542dda2
You may get the warning
Message failed to publish on IPFS and/or P2P.
This is common and usually not an issue.
ℹ The second URL uses a hostname dedicated to your VM. Aleph.im identifiers are too long to work for URL subdomains, so a base32 encoded version of the identifier is used instead.
ℹ You can make your own domain point to the VM. See the advanced section.
Run your program
You can now run your program by opening one of the URLs above. Each URL is unique for one program.
This will automatically start your program inside a VM on the aleph.im Compute Resource Node behind
aleph.sh domain name and serve your request.
An important thing to notice is that we did not install any specific dependency for our program, despite relying on FastAPI. This is because the official aleph.im runtime is already pre-configured with several typical Python packages. Of course, you can customize your program to add your own requirements. Refer to Adding Python dependencies to a program for more information.
Check out Building a Rust microVM to run a program written in another language than Python.
Check out Advanced Python program features for more options and capabilities.