Hero Compute Registry

VM image registry for Hero Compute. Defines available images and contains Dockerfiles for custom builds.

Structure

hero_compute_registry/
├── images.toml          # Image definitions (loaded by hero_compute_server)
├── .forgejo/workflows/  # CI: auto-build and push on every commit
└── images/              # Custom Dockerfiles
    ├── alpine/
    ├── ubuntu-24.04/
    ├── ubuntu-22.04/
    ├── ubuntu-20.04/
    └── debian/

SSH Access

All images use SSH key authentication only — no passwords. Password auth is disabled.

To access a VM:

1. Add your SSH public key in the Hero Compute Settings page
2. Deploy and start a VM
3. Connect: ssh root@<mycelium-ipv6>

Your SSH keys are injected into the VM's /root/.ssh/authorized_keys at deploy time and on every start.

Required Packages for Custom Images

Hero Compute VMs run inside chvm micro-VMs with TAP + Mycelium networking. Custom images must include certain packages for networking and SSH to work correctly.

Required

Package	Why
openssh-server	SSH access into the VM
iproute2	chvm-init uses ip to configure networking (IP address, default route). Without it, the VM has no internet access.

Recommended

Package	Why
bash	Default shell for exec commands
curl	Useful for debugging and downloading tools
iputils-ping	Debugging network connectivity

Dockerfile Requirements

Every image must:

1. Install iproute2 — without it, chvm-init cannot add the default IPv4 route and the VM will have no internet access (DNS fails, apt update fails, etc.)
2. Install and configure openssh-server — with key-only auth, no passwords
3. Create /run/sshd — required by openssh-server's privilege separation
4. Set CMD to sshd — ["/usr/sbin/sshd", "-D", "-e"]
5. Prepare /root/.ssh/authorized_keys — hero_compute injects SSH keys here after boot

Minimal Dockerfile Template (Debian/Ubuntu)

FROM ubuntu:24.04

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
       openssh-server iproute2 bash iputils-ping curl \
    && mkdir -p /run/sshd \
    && sed -i 's/#PermitRootLogin.*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config \
    && sed -i 's/#PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config \
    && sed -i 's/#PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config \
    && mkdir -p /root/.ssh \
    && chmod 700 /root/.ssh \
    && touch /root/.ssh/authorized_keys \
    && chmod 600 /root/.ssh/authorized_keys \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Add your application packages here
# RUN apt-get update && apt-get install -y nginx ...

EXPOSE 22
CMD ["/usr/sbin/sshd", "-D", "-e"]

Minimal Dockerfile Template (Alpine)

FROM alpine:latest

RUN apk add --no-cache openssh-server iproute2 bash iputils curl \
    && ssh-keygen -A \
    && sed -i 's/#PermitRootLogin.*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config \
    && sed -i 's/#PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config \
    && sed -i 's/#PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config \
    && mkdir -p /root/.ssh \
    && chmod 700 /root/.ssh \
    && touch /root/.ssh/authorized_keys \
    && chmod 600 /root/.ssh/authorized_keys

# Add your application packages here
# RUN apk add --no-cache nginx ...

EXPOSE 22
CMD ["/usr/sbin/sshd", "-D", "-e"]

Adding Images

From Public Registries

Add an entry to images.toml:

[[images]]
name = "Nginx"
reference = "nginx:alpine"
description = "Nginx web server on Alpine"

Note: Public images that don't include iproute2 and openssh-server will not have SSH access or internet connectivity. Build a custom image instead.

Custom Images (Forgejo)

1. Create a Dockerfile in images/ using the templates above
2. Build and push:

docker build -t forge.ourworld.tf/lhumina_code/hero_compute_registry/my-app:latest images/my-app/
docker login forge.ourworld.tf
docker push forge.ourworld.tf/lhumina_code/hero_compute_registry/my-app:latest

3. Add to images.toml:

[[images]]
name = "My App"
reference = "forge.ourworld.tf/lhumina_code/hero_compute_registry/my-app:latest"
description = "Custom image with nginx"

4. On each node, login to the registry (if private):

chvm login forge.ourworld.tf -u <username> -p <token>

Build All Images

docker login forge.ourworld.tf

for img in ubuntu-24.04 ubuntu-22.04 ubuntu-20.04 alpine debian; do
  docker build -t forge.ourworld.tf/lhumina_code/hero_compute_registry/${img}:latest images/${img}/
  docker push forge.ourworld.tf/lhumina_code/hero_compute_registry/${img}:latest
done

CI/CD

The .forgejo/workflows/build-images.yml workflow automatically builds and pushes all images on every push to development or main that modifies images/ or images.toml.

Configuration

The hero_compute_server fetches images.toml from this repo at runtime. Override the URL with:

HERO_COMPUTE_REGISTRY_URL=https://forge.ourworld.tf/lhumina_code/hero_compute_registry/raw/branch/main/images.toml

Default Image

Mark one image with default = true. This image is pre-selected in the deploy UI:

[[images]]
name = "Ubuntu 24.04"
reference = "forge.ourworld.tf/lhumina_code/hero_compute_registry/ubuntu-24.04:latest"
default = true