From 7ccab61a1baea2e636b62d74c5a91ac68da3a72e Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Mon, 9 Mar 2026 18:56:33 -0300 Subject: [PATCH] Refresh release docs for Docker Hub environments --- README.md | 12 ++++++++---- docs/host-requirements.md | 1 + docs/install.md | 8 ++++++++ docs/public-contract.md | 20 +++++++++++++++++++- docs/troubleshooting.md | 4 ++++ runtime_sources/README.md | 6 ++++-- 6 files changed, 44 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5c34f26..b72876c 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,9 @@ Current official environments in the shipped catalog: - `debian:12-build` The package ships the embedded Firecracker runtime and a package-controlled environment catalog. -Official environments are pulled as OCI artifacts from Docker Hub into a local cache on first use or -through `pyro env pull`. +Official environments are pulled as OCI artifacts from public Docker Hub repositories into a local +cache on first use or through `pyro env pull`. +End users do not need registry credentials to pull or run official environments. ## CLI @@ -198,13 +199,16 @@ Official environment publication is automated through For a local publish against Docker Hub: ```bash +export DOCKERHUB_USERNAME='your-dockerhub-username' +export DOCKERHUB_TOKEN='your-dockerhub-token' make runtime-materialize -OCI_REGISTRY_USERNAME="$DOCKERHUB_USERNAME" OCI_REGISTRY_PASSWORD="$DOCKERHUB_TOKEN" \ - make runtime-publish-official-environments-oci +make runtime-publish-official-environments-oci ``` `make runtime-publish-environment-oci` auto-exports the OCI layout for the selected environment if it is missing. +The publisher accepts either `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` or +`OCI_REGISTRY_USERNAME` and `OCI_REGISTRY_PASSWORD`. Docker Hub uploads are chunked by default for large rootfs layers; if you need to tune a slow link, use `PYRO_OCI_UPLOAD_TIMEOUT_SECONDS`, `PYRO_OCI_UPLOAD_CHUNK_SIZE_BYTES`, and `PYRO_OCI_REQUEST_TIMEOUT_SECONDS`. diff --git a/docs/host-requirements.md b/docs/host-requirements.md index 4023e39..81d0754 100644 --- a/docs/host-requirements.md +++ b/docs/host-requirements.md @@ -7,6 +7,7 @@ - KVM available at `/dev/kvm` - support for Firecracker microVMs - sufficient disk for the embedded runtime files and cached OCI environment images +- outbound HTTPS access to `registry-1.docker.io` for first-run installs or `pyro env pull` ## Required For Guest Networking diff --git a/docs/install.md b/docs/install.md index f06e691..068d44a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,6 +4,7 @@ - Linux x86_64 host - Python 3.12+ +- `uv` - `/dev/kvm` If you want outbound guest networking: @@ -20,6 +21,12 @@ Run the MCP server directly from the package without a manual install: uvx --from pyro-mcp pyro mcp serve ``` +Prefetch the default official environment: + +```bash +uvx --from pyro-mcp pyro env pull debian:12 +``` + Run one command in a curated environment: ```bash @@ -38,6 +45,7 @@ uvx --from pyro-mcp pyro env list uv tool install pyro-mcp pyro --version pyro env list +pyro env pull debian:12 pyro env inspect debian:12 pyro doctor ``` diff --git a/docs/public-contract.md b/docs/public-contract.md index 1497958..f446d0d 100644 --- a/docs/public-contract.md +++ b/docs/public-contract.md @@ -45,9 +45,27 @@ Primary facade: - `Pyro` -Supported public methods: +Supported public entrypoints: +- `create_server()` - `Pyro.create_server()` +- `Pyro.list_environments()` +- `Pyro.pull_environment(environment)` +- `Pyro.inspect_environment(environment)` +- `Pyro.prune_environments()` +- `Pyro.create_vm(...)` +- `Pyro.start_vm(vm_id)` +- `Pyro.exec_vm(vm_id, *, command, timeout_seconds=30)` +- `Pyro.stop_vm(vm_id)` +- `Pyro.delete_vm(vm_id)` +- `Pyro.status_vm(vm_id)` +- `Pyro.network_info_vm(vm_id)` +- `Pyro.reap_expired()` +- `Pyro.run_in_vm(...)` + +Stable public method names: + +- `create_server()` - `list_environments()` - `pull_environment(environment)` - `inspect_environment(environment)` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 5bd9cef..54a4375 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -7,6 +7,7 @@ Cause: - the environment cache directory is not writable - the configured registry artifact is unavailable - the environment download was interrupted +- the host cannot reach `registry-1.docker.io` Fix: @@ -16,6 +17,9 @@ pyro env prune pyro env pull debian:12 ``` +If you are validating a freshly published official environment, also verify that the corresponding +Docker Hub repository is public. + ## `pyro run --network` fails before the guest starts Cause: diff --git a/runtime_sources/README.md b/runtime_sources/README.md index 356beed..0c7fccb 100644 --- a/runtime_sources/README.md +++ b/runtime_sources/README.md @@ -17,14 +17,16 @@ Materialization workflow: Official environment publication workflow: 1. `make runtime-materialize` -2. `OCI_REGISTRY_USERNAME=... OCI_REGISTRY_PASSWORD=... make runtime-publish-official-environments-oci` +2. `DOCKERHUB_USERNAME=... DOCKERHUB_TOKEN=... make runtime-publish-official-environments-oci` 3. or run the repo workflow at `.github/workflows/publish-environments.yml` with Docker Hub credentials 4. if your uplink is slow, tune publishing with `PYRO_OCI_UPLOAD_TIMEOUT_SECONDS`, `PYRO_OCI_UPLOAD_CHUNK_SIZE_BYTES`, and `PYRO_OCI_REQUEST_TIMEOUT_SECONDS` +Official end-user pulls are anonymous; registry credentials are only required for publishing. + Build requirements for the real path: - `docker` - outbound network access to GitHub and Debian snapshot mirrors -- enough disk for a kernel build plus 2G ext4 images per profile +- enough disk for a kernel build plus 2G ext4 images per source profile Kernel build note: - the kernel builder now defaults to conservative parallelism to avoid compiler crashes on memory-constrained hosts