Building machine images¶

Sistemo runs ext4 rootfs images, not Docker containers.

Info

sistemo image build automatically installs openssh-server via chroot if the Docker image doesn't already have it. It also injects the SSH key and /init script. Any Docker image works out of the box — no special Dockerfile modifications needed.

Supported package managers for auto-install: apt (Debian/Ubuntu), apk (Alpine), dnf (Fedora), yum (CentOS), pacman (Arch).

Options¶

Method	When to use
Registry images	Quickest — pre-built images for common distros
From Docker	Custom images with your packages pre-installed
Direct URL	Use a pre-built rootfs from any HTTP source
Dashboard	Browse, download, and build images from the web dashboard

Registry images¶

Images are pulled from registry.sistemo.io by default. Override with the SISTEMO_REGISTRY_URL environment variable.

# List available images
sistemo image list

# Pull an image to local cache
sistemo image pull debian

# Deploy (pulls automatically if not cached)
sistemo machine deploy debian

Build from Docker¶

Any Docker image works. sistemo image build will auto-install openssh-server if it's missing.

# Build any Docker image
docker build -t myimage .

# Convert to rootfs (requires root for mount/chroot)
sudo sistemo image build myimage

You can also build directly from Docker Hub images:

sudo sistemo image build nginx:latest
sudo sistemo image build node:20
sudo sistemo image build python:3.12

This saves myimage.rootfs.ext4 to ~/.sistemo/images/. Deploy it by name:

sistemo machine deploy myimage --name my-custom-vm

Custom output path¶

Pass the output path as the second argument (default is ~/.sistemo/images/<name>.rootfs.ext4):

sudo sistemo image build myimage /path/to/custom.rootfs.ext4

Custom rootfs size¶

By default, rootfs images are 2 GB. Override with:

ROOTFS_MB=1024 sudo sistemo image build myimage

Low-resource machines¶

On machines with limited RAM or disk (e.g. 512 MB / 10 GB VPS), the build may be slow. Consider:

Using ROOTFS_MB=1024 to reduce the image size
Building on a larger machine and copying the rootfs file over

Direct URL¶

sistemo machine deploy https://example.com/images/debian.rootfs.ext4

The image is downloaded, cached in ~/.sistemo/images/, and deployed. Subsequent deploys of the same URL use the cached copy.

Dashboard

All image operations are also available from the web dashboard — browse the registry, build from Docker images with real-time progress, and delete unused images without touching the CLI.