Skip to content

linux.md

Latest commit

 

History

History
102 lines (68 loc) · 2.34 KB

linux.md

File metadata and controls

102 lines (68 loc) · 2.34 KB

Linux setup guide

This guide is for running docker2vm on Linux hosts.

docker2vm includes a pinned Gondolin runtime dependency (@earendil-works/gondolin@0.2.1) to resolve guest assets during conversion.

1) Install required tools

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y curl unzip e2fsprogs qemu-system-x86

Install Bun:

curl -fsSL https://bun.sh/install | bash
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

If you want Dockerfile conversion (dockerfile2gondolin), install Docker and Buildx.

2) Optional: install Gondolin CLI (for running generated assets)

docker2vm is tested with @earendil-works/gondolin@0.2.1 and can fetch guest assets automatically during conversion.

Install the CLI globally if you want to execute generated assets via gondolin exec:

bun add -g @earendil-works/gondolin@0.2.1

3) Verify toolchain

bun --version
qemu-system-x86_64 --version
mke2fs -V
debugfs -V
gondolin --help >/dev/null

4) Validate from source checkout

bun run test
bun run typecheck
bun run build

5) Choose the build platform

Use a platform that matches the architecture you will run in Gondolin.

  • uname -m => x86_64 or amd64: use linux/amd64
  • uname -m => aarch64 or arm64: use linux/arm64

oci2gondolin defaults automatically from host arch if --platform is omitted, but passing it explicitly is recommended.

Example:

bun run oci2gondolin -- \
  --image busybox:latest \
  --platform linux/amd64 \
  --mode assets \
  --out ./out/busybox-assets

6) Run integration + smoke checks

amd64 host:

INTEGRATION_PLATFORM=linux/amd64 bun run test:integration
PLATFORM=linux/amd64 bun run e2e:smoke

arm64 host:

INTEGRATION_PLATFORM=linux/arm64 bun run test:integration
PLATFORM=linux/arm64 bun run e2e:smoke

Notes on virtualization performance

  • If /dev/kvm is available, QEMU can use hardware acceleration.
  • If /dev/kvm is unavailable (common in CI), the project falls back to TCG emulation (slower but functional).

Troubleshooting

sandbox_stopped / VM exits quickly

Confirm QEMU is installed and that you are using a platform that matches your host and assets.

mke2fs or debugfs missing

Reinstall e2fsprogs and verify the commands are available in your shell.