{"id":24370082,"url":"https://github.com/unikraft/app-python3","last_synced_at":"2025-07-01T06:38:51.696Z","repository":{"id":35714445,"uuid":"217256209","full_name":"unikraft/app-python3","owner":"unikraft","description":"Unikraft Python3 app repo","archived":false,"fork":false,"pushed_at":"2023-12-30T05:49:43.000Z","size":43355,"stargazers_count":12,"open_issues_count":6,"forks_count":10,"subscribers_count":8,"default_branch":"stable","last_synced_at":"2025-04-10T17:58:04.762Z","etag":null,"topics":["python3","unikernel","unikraft-application"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unikraft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-24T09:00:32.000Z","updated_at":"2024-06-17T08:38:41.000Z","dependencies_parsed_at":"2023-01-16T03:45:15.129Z","dependency_job_id":"628171be-3a2c-42ef-8535-47b28019cbb1","html_url":"https://github.com/unikraft/app-python3","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/unikraft/app-python3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-python3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-python3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-python3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-python3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unikraft","download_url":"https://codeload.github.com/unikraft/app-python3/tar.gz/refs/heads/stable","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-python3/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262915546,"owners_count":23383847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python3","unikernel","unikraft-application"],"created_at":"2025-01-19T04:12:33.560Z","updated_at":"2025-07-01T06:38:51.666Z","avatar_url":"https://github.com/unikraft.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python3 on Unikraft\n\nThis application starts a Python3 web application with Unikraft.\nFollow the instructions below to set up, configure, build and run Python3.\n\nTo get started immediately, you can use Unikraft's companion command-line companion tool, [`kraft`](https://github.com/unikraft/kraftkit).\nStart by running the interactive installer:\n\n```console\ncurl --proto '=https' --tlsv1.2 -sSf https://get.kraftkit.sh | sudo sh\n```\n\nOnce installed, clone [this repository](https://github.com/unikraft/app-python3) and run `kraft build`:\n\n```console\ngit clone https://github.com/unikraft/app-python3 python3\ncd python3/\nkraft build\n```\n\nThis will guide you through an interactive build process where you can select one of the available targets (architecture/platform combinations).\nOtherwise, we recommend building for `qemu/x86_64` like so:\n\n```console\nkraft build --arch x86_64 --plat qemu\n```\n\nOnce built, you can instantiate the unikernel via:\n\n```console\ntar xvf rootfs.tar.gz -C rootfs/\nkraft run --initrd rootfs/ -M 256M\n```\n\nWhen left without any input flags, you'll be queried for the desired target architecture/platform.\n\nIf you are running on a virtual machine, or a system without KVM support, disable hardware acceleration by using the `-W` command line flag:\n\n```console\nkraft run -W --initrd rootfs/ -M 256M\n```\n\nThis starts a Python3 console in a virtual machine.\nNote that KraftKit currently doesn't provide you the means to interact with the Python3 console in the virtual machine.\nFor that, see more below.\n\n## Quick Setup (aka TLDR)\n\nFor a quick setup, run the commands below.\nNote that you still need to install the [requirements](#requirements).\n\nFor building and running everything for `x86_64`, follow the steps below:\n\n```console\ngit clone https://github.com/unikraft/app-python3 python3\ncd python3/\n./script/setup.sh\nwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.py\nchmod a+x scripts/generate.py\n./scripts/generate.py\n./scripts/build/make-qemu-x86_64-9pfs.sh\n./scripts/run/qemu-x86_64-9pfs-interp.sh\n```\n\nThis will configure, build and run the `Python3` application, resulting in a Python3 console being started.\n\nThe same can be done for `AArch64`, by running the commands below:\n\n```console\ngit clone https://github.com/unikraft/app-python3 python3\ncd python3/\n./scripts/setup.sh\nwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.py\nchmod a+x scripts/generate.py\n./scripts/generate.py\n./scripts/build/make-qemu-arm64-9pfs.sh\n./scripts/run/qemu-arm64-9pfs-interp.sh\n```\n\nClose the QEMU instance by using the `Ctrl+a x` keyboard combination.\nThat is, press `Ctrl` and `a` simultaneously, then release and press `x`.\n\nInformation about every step is detailed below.\n\n## Requirements\n\nIn order to set up, configure, build and run Python3 on Unikraft, the following packages are required:\n\n* `build-essential` / `base-devel` / `@development-tools` (the meta-package that includes `make`, `gcc` and other development-related packages)\n* `sudo`\n* `flex`\n* `bison`\n* `git`\n* `wget`\n* `uuid-runtime`\n* `qemu-system-x86`\n* `qemu-system-arm`\n* `qemu-kvm`\n* `sgabios`\n* `gcc-aarch64-linux-gnu`\n\nGCC \u003e= 8 is required to build Python3 on Unikraft.\n\nOn Ubuntu/Debian or other `apt`-based distributions, run the following command to install the requirements:\n\n```console\nsudo apt install -y --no-install-recommends \\\n  build-essential \\\n  sudo \\\n  gcc-aarch64-linux-gnu \\\n  libncurses-dev \\\n  libyaml-dev \\\n  flex \\\n  bison \\\n  git \\\n  wget \\\n  uuid-runtime \\\n  qemu-kvm \\\n  qemu-system-x86 \\\n  qemu-system-arm \\\n  sgabios\n```\n\nIn case you require networking support, such as starting a Python HTTP server, a specific configuration must be enabled for QEMU.\nRun the commands below to enable that configuration (for the network bridge to work):\n\n```console\nsudo mkdir /etc/qemu/\necho \"allow all\" | sudo tee /etc/qemu/bridge.conf\n```\n\n## Set Up\n\nThe following repositories are required for Python3:\n\n* The application repository (this repository): [`app-python3`](https://github.com/unikraft/app-python3)\n* The Unikraft core repository: [`unikraft`](https://github.com/unikraft/unikraft)\n* Library repositories:\n  * The Python3 \"library\" repository: [`lib-python3`](https://github.com/unikraft/lib-python3)\n  * The standard C library: [`lib-musl`](https://github.com/unikraft/lib-musl)\n  * The networking stack library: [`lib-lwip`](https://github.com/unikraft/lib-lwip)\n  * The compiler runtime library: [`lib-compiler-rt`](https://github.com/unikraft/lib-compiler-rt)\n\nFollow the steps below for the setup:\n\n  1. First clone the [`app-python3` repository](https://github.com/unikraft/app-python3) in the `python3/` directory:\n\n     ```console\n     git clone https://github.com/unikraft/app-python3 python3\n     ```\n\n     Enter the `python3/` directory:\n\n     ```console\n     cd python3/\n     ls -F\n     ```\n\n     This will show you the contents of the repository:\n\n     ```text\n     defconfigs/  kraft.cloud.yaml  kraft.yaml  Makefile  Makefile.uk  README.md  rootfs.tar.gz  scripts/\n     ```\n\n  1. While inside the `python3/` directory, clone all required repositories by using the `setup.sh` script:\n\n     ```console\n     ./scripts/setup.sh\n     ```\n\n  1. Use the `tree` command to inspect the contents of the `workdir/` directory.\n     It should print something like this:\n\n     ```console\n     tree -F -L 2 workdir/\n     ```\n\n     The layout of the `workdir/` directory should look something like this:\n\n     ```text\n     workdir/\n     |-- libs/\n     |   |-- compiler-rt/\n     |   |-- lwip/\n     |   |-- musl/\n     |   `-- python3/\n     `-- unikraft/\n         |-- arch/\n         |-- Config.uk\n         |-- CONTRIBUTING.md\n         |-- COPYING.md\n         |-- include/\n         |-- lib/\n         |-- Makefile\n         |-- Makefile.uk\n         |-- plat/\n         |-- README.md\n         |-- support/\n         `-- version.mk\n\n     10 directories, 7 files\n     ```\n\n## Scripted Building and Running\n\nTo build and run Unikraft images, it's easiest to generate build and running scripts and use those.\n\nFirst of all, grab the [`generate.py` script](https://github.com/unikraft/app-testing/blob/staging/scripts/generate.py) and place it in the `scripts/` directory by running:\n\n```console\nwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.py\nchmod a+x scripts/generate.py\n```\n\nNow, run the `generate.py` script.\nYou must run it in the root directory of this repository:\n\n```console\n./scripts/generate.py\n```\n\nRunning the script will generate build and run scripts in the `scripts/build/` and the `scripts/run/` directories:\n\n```text\nscripts/\n|-- build/\n|   |-- kraft-fc-arm64-initrd.sh*\n|   |-- kraft-fc-x86_64-initrd.sh*\n|   |-- kraft-qemu-arm64-9pfs.sh*\n|   |-- kraft-qemu-arm64-initrd.sh*\n|   |-- kraft-qemu-x86_64-9pfs.sh*\n|   |-- kraft-qemu-x86_64-initrd.sh*\n|   |-- make-fc-arm64-initrd.sh*\n|   |-- make-fc-x86_64-initrd.sh*\n|   |-- make-qemu-arm64-9pfs.sh*\n|   |-- make-qemu-arm64-initrd.sh*\n|   |-- make-qemu-x86_64-9pfs.sh*\n|   `-- make-qemu-x86_64-initrd.sh*\n|-- generate.py*\n|-- run/\n|   |-- fc-arm64-initrd-http-server.json\n|   |-- fc-arm64-initrd-http-server.sh*\n[...]\n|   |-- kraft-qemu-arm64-initrd-http-server.sh*\n|   |-- kraft-qemu-arm64-initrd-interp.sh*\n|   |-- kraft-qemu-x86_64-9pfs-http-server.sh*\n[...]\n|   |-- qemu-x86_64-initrd-http-server.sh*\n|   `-- qemu-x86_64-initrd-interp.sh*\n|-- run.yaml\n`-- setup.sh*\n```\n\nThey are shell scripts, so you can use an editor or a text viewer to check their contents:\n\n```console\ncat scripts/run/qemu-x86_64-initrd-http-server.sh\n```\n\nYou can now build and run images for different configurations\n\nFor example, to build and run for Firecracker on x86_64, run:\n\n```console\n./scripts/build/make-fc-x86_64-initrd.sh\n./scripts/run/fc-x86_64-initrd-interp.sh\n```\n\nTo build and run for QEMU on x86_64 using KraftKit, run:\n\n```console\n./scripts/build/kraft-qemu-x86_64-9pfs.sh\n./scripts/run/kraft-qemu-x86_64-9pfs-interp.sh\n```\n\nThe run script will start a Python3 console inside a Unikraft virtual machine.\nYou can run Python commands at the prompt.\n\nClose KraftKit-opened instances by running `Ctrl+c`.\nThen, check the open instances by using `kraft ps` or `sudo kraft ps.\nStop the instances by running `kraft stop \u003cinstance-id\u003e`.\n\nClose the QEMU instance by using the `Ctrl+a x` keyboard combination.\nThat is, press `Ctrl` and `a` simultaneously, then release and press `x`.\n\nFor Firecracker, you would have to kill the process by issuing a command.\nSimplest is to open up another console and run:\n\n```console\npkill -f firecracker\n```\n\n## Detailed Steps\n\n### Configure\n\nConfiguring, building and running a Unikraft application depends on our choice of platform and architecture.\nCurrently, supported platforms are QEMU (KVM), Xen and linuxu.\nQEMU (KVM) is known to be working, so we focus on that.\n\nSupported architectures are x86_64 and AArch64.\n\nUse the corresponding the configuration files in `defconfigs/`, according to your choice of platform and architecture.\n\n#### QEMU x86_64\n\nUse the `defconfigs/qemu-x86_64-9pfs` configuration file together with `make defconfig` to create the configuration file:\n\n```console\nUK_DEFCONFIG=$(pwd)/defconfigs/qemu-x86_64-9pfs make defconfig\n```\n\nThis results in the creation of the `.config` file:\n\n```console\nls .config\n.config\n```\n\nThe `.config` file will be used in the build step.\n\n#### QEMU AArch64\n\nUse the `defconfigs/qemu-arm64-9pfs` configuration file together with `make defconfig` to create the configuration file:\n\n```console\nUK_DEFCONFIG=$(pwd)/defconfigs/qemu-arm64-9pfs make defconfig\n```\n\nSimilar to the x86_64 configuration, this results in the creation of the `.config` file that will be used in the build step.\n\n### Build\n\nBuilding uses as input the `.config` file from above, and results in a unikernel image as output.\nThe unikernel output image, together with intermediary build files, are stored in the `build/` directory.\n\n#### Clean Up\n\nBefore starting a build on a different platform or architecture, you must clean up the build output.\nThis may also be required in case of a new configuration.\n\nCleaning up is done with 3 possible commands:\n\n* `make clean`: cleans all actual build output files (binary files, including the unikernel image)\n* `make properclean`: removes the entire `build/` directory\n* `make distclean`: removes the entire `build/` directory **and** the `.config` file\n\nTypically, you would use `make properclean` to remove all build artifacts, but keep the configuration file.\n\n#### QEMU x86_64\n\nBuilding for QEMU x86_64 assumes you did the QEMU x86_64 configuration step above.\nBuild the Unikraft Python3 image for QEMU x86_64 by using the commands below:\n\n```console\nmake prepare\nmake -j $(nproc)\n```\n\nYou can see a list of all the files processed by the build system:\n\n```text\n[...]\n  LD      python3_qemu-x86_64.dbg\n  UKBI    python3_qemu-x86_64.dbg.bootinfo\n  SCSTRIP python3_qemu-x86_64\n  GZ      python3_qemu-x86_64.gz\nmake[1]: Leaving directory '/media/stefan/projects/unikraft/scripts/workdir/apps/app-python3/workdir/unikraft'\n```\n\nAt the end of the build command, the `python3_qemu-x86_64` unikernel image is generated.\nThis image is to be used in the run step.\n\n#### QEMU AArch64\n\nIf you had configured and build a unikernel image for another platform or architecture (such as x86_64) before, then:\n\n1. Do a cleanup step with `make properclean`.\n\n1. Configure for QEMU AAarch64, as shown above.\n\n1. Follow the instructions below to build for QEMU AArch64.\n\nBuilding for QEMU AArch64 assumes you did the QEMU AArch64 configuration step above.\nBuild the Unikraft Python3 image for QEMU AArch64 by using the same command as for x86_64:\n\n```console\nmake prepare\nmake -j $(nproc)\n```\n\nSame as when building for x86_64, you can see a list of all the files \n\n```text\n[...]\n  LD      python3_qemu-arm64.dbg\n  UKBI    python3_qemu-arm64.dbg.bootinfo\n  SCSTRIP python3_qemu-arm64\n  GZ      python3_qemu-arm64.gz\nmake[1]: Leaving directory '/media/stefan/projects/unikraft/scripts/workdir/apps/app-python3/workdir/unikraft'\n```\n\nSimilarly to x86_64, at the end of the build command, the `python3_qemu-arm64` unikernel image is generated.\nThis image is to be used in the run step.\n\n### Run\n\nRun the resulting image using `qemu-system`.\n\nBefore that, unpack the root filesystem:\n\n```console\nmkdir rootfs\ntar xf rootfs.tar.gz -C rootfs\n```\n\n#### QEMU x86_64\n\nTo run the QEMU x86_64 build, use `qemu-system-x86_64`:\n\n```console\nsudo qemu-system-x86_64 \\\n    -accel kvm \\\n    -fsdev local,id=myid,path=\"$(pwd)/rootfs\",security_model=none \\\n    -device virtio-9p-pci,fsdev=myid,mount_tag=fs1,disable-modern=on,disable-legacy=off \\\n    -kernel build/python3_qemu-x86_64 -nographic\n```\n\nThis will open up a Python3 console:\n\n```text\nen1: Added\nen1: Interface is up\nPowered by\no.   .o       _ _               __ _\nOo   Oo  ___ (_) | __ __  __ _ ' _) :_\noO   oO ' _ `| | |/ /  _)' _` | |_|  _)\noOo oOO| | | | |   (| | | (_) |  _) :_\n OoOoO ._, ._:_:_,\\_._,  .__,_:_, \\___)\n                  Atlas 0.13.1~5eb820bd\nPython 3.7.4 (default, Jul  1 2023, 16:22:09) \n[GCC 9.4.0] on unknown\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n\u003e\u003e\u003e print(\"Hello, World!\")\nHello, World!\n\u003e\u003e\u003e\n```\n\nClose the QEMU instance by using the `Ctrl+a x` keyboard combination.\nThat is, press `Ctrl` and `a` simultaneously, then release and press `x`.\n\n#### QEMU AArch64\n\nTo run the AArch64 build, use `qemu-system-aarch64`:\n\n```console\nsudo qemu-system-aarch64 \\\n    -fsdev local,id=myid,path=\"$(pwd)/rootfs\",security_model=none \\\n    -device virtio-9p-pci,fsdev=myid,mount_tag=fs1,disable-modern=on,disable-legacy=off \\\n    -kernel build/python3_qemu-arm64 -nographic \\\n    -machine virt -cpu cortex-a57\n```\n\nJust like when running for x86_64, this will run the Python3 application:\n\n```text\nen1: Added\nen1: Interface is up\nPowered by\no.   .o       _ _               __ _\nOo   Oo  ___ (_) | __ __  __ _ ' _) :_\noO   oO ' _ `| | |/ /  _)' _` | |_|  _)\noOo oOO| | | | |   (| | | (_) |  _) :_\n OoOoO ._, ._:_:_,\\_._,  .__,_:_, \\___)\n                  Atlas 0.13.1~5eb820bd\nPython 3.7.4 (default, Jul  1 2023, 16:22:09) \n[GCC 9.4.0] on unknown\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n\u003e\u003e\u003e print(\"Hello, World!\")\nHello, World!\n\u003e\u003e\u003e\n```\n\nSimilarly, to close the QEMU Python3 server, use the `Ctrl+a x` keyboard shortcut.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikraft%2Fapp-python3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funikraft%2Fapp-python3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikraft%2Fapp-python3/lists"}