Skip to content

Commit 466766a

Browse files
vmg-devvmg-dev
committed
Add platform setup guides for macOS and Linux
1 parent 45d8c41 commit 466766a

3 files changed

Lines changed: 205 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# docker2vm
22

3-
`docker2vm` converts OCI container images (or Dockerfiles via BuildKit) into VM-compatible outputs. Today, the runtime materialization target is Gondolin.
3+
`docker2vm` converts OCI container images (or Dockerfiles via BuildKit) into VM-compatible outputs. Today, the runtime materialization target is [Gondolin](https://github.com/earendil-works/gondolin).
44

55
It follows an OCI-first flow inspired by "Docker without Docker":
66

@@ -53,6 +53,11 @@ Ubuntu helpers:
5353
sudo apt-get install -y e2fsprogs qemu-system-x86
5454
```
5555

56+
## Platform setup guides
57+
58+
- [macOS guide](./docs/macos.md)
59+
- [Linux guide](./docs/linux.md)
60+
5661
## Install
5762

5863
```bash
@@ -75,6 +80,21 @@ bun run build
7580
bun run test:integration
7681
```
7782

83+
### Choosing the build platform (`--platform`)
84+
85+
`--platform` selects which OCI image variant to convert, and should match the architecture you plan to run in Gondolin.
86+
87+
- Apple Silicon / arm64 Linux hosts: `linux/arm64`
88+
- Intel / amd64 hosts: `linux/amd64`
89+
- If omitted, `oci2gondolin` defaults from host arch (`x64 -> linux/amd64`, `arm64 -> linux/arm64`).
90+
91+
For helper scripts:
92+
93+
- `e2e:smoke` uses `PLATFORM`
94+
- integration tests use `INTEGRATION_PLATFORM`
95+
96+
Cross-arch builds are possible at image-selection time, but for reliable runtime execution you should use a platform that matches the runtime guest architecture.
97+
7898
### 2) Convert image -> assets
7999

80100
```bash
@@ -176,4 +196,5 @@ dockerfile2gondolin --file PATH --context PATH --out PATH [options]
176196
## Repo notes
177197

178198
- This repo is standalone; Gondolin core is not modified.
199+
- Gondolin upstream repository: https://github.com/earendil-works/gondolin
179200
- `out/` is generated output and ignored by git.

‎docs/linux.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Linux setup guide
2+
3+
This guide is for running `docker2vm` on Linux hosts.
4+
5+
## 1) Install required tools
6+
7+
### Ubuntu / Debian
8+
9+
```bash
10+
sudo apt-get update
11+
sudo apt-get install -y curl unzip e2fsprogs qemu-system-x86
12+
```
13+
14+
Install Bun:
15+
16+
```bash
17+
curl -fsSL https://bun.sh/install | bash
18+
source ~/.bashrc
19+
```
20+
21+
If you want Dockerfile conversion (`dockerfile2gondolin`), install Docker and Buildx.
22+
23+
## 2) Verify toolchain
24+
25+
```bash
26+
bun --version
27+
qemu-system-x86_64 --version
28+
mke2fs -V
29+
debugfs -V
30+
```
31+
32+
## 3) Install dependencies and validate
33+
34+
```bash
35+
bun install
36+
bun run test
37+
bun run typecheck
38+
bun run build
39+
```
40+
41+
## 4) Choose the build platform
42+
43+
Use a platform that matches the architecture you will run in Gondolin.
44+
45+
- `uname -m` => `x86_64` or `amd64`: use `linux/amd64`
46+
- `uname -m` => `aarch64` or `arm64`: use `linux/arm64`
47+
48+
`oci2gondolin` defaults automatically from host arch if `--platform` is omitted, but passing it explicitly is recommended.
49+
50+
Example:
51+
52+
```bash
53+
bun run oci2gondolin -- \
54+
--image busybox:latest \
55+
--platform linux/amd64 \
56+
--mode assets \
57+
--out ./out/busybox-assets
58+
```
59+
60+
## 5) Run integration + smoke checks
61+
62+
amd64 host:
63+
64+
```bash
65+
INTEGRATION_PLATFORM=linux/amd64 bun run test:integration
66+
PLATFORM=linux/amd64 bun run e2e:smoke
67+
```
68+
69+
arm64 host:
70+
71+
```bash
72+
INTEGRATION_PLATFORM=linux/arm64 bun run test:integration
73+
PLATFORM=linux/arm64 bun run e2e:smoke
74+
```
75+
76+
## Notes on virtualization performance
77+
78+
- If `/dev/kvm` is available, QEMU can use hardware acceleration.
79+
- If `/dev/kvm` is unavailable (common in CI), the project falls back to TCG emulation (slower but functional).
80+
81+
## Troubleshooting
82+
83+
### `sandbox_stopped` / VM exits quickly
84+
85+
Confirm QEMU is installed and that you are using a platform that matches your host and assets.
86+
87+
### `mke2fs` or `debugfs` missing
88+
89+
Reinstall `e2fsprogs` and verify the commands are available in your shell.

‎docs/macos.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# macOS setup guide
2+
3+
This guide is for running `docker2vm` on macOS (Apple Silicon or Intel).
4+
5+
## 1) Install required tools
6+
7+
```bash
8+
brew install bun qemu e2fsprogs
9+
```
10+
11+
If you want Dockerfile conversion (`dockerfile2gondolin`), also install Docker Desktop.
12+
13+
## 2) Ensure `mke2fs` and `debugfs` are on `PATH`
14+
15+
`e2fsprogs` is often keg-only on macOS.
16+
17+
### Apple Silicon (`/opt/homebrew`)
18+
19+
```bash
20+
echo 'export PATH="/opt/homebrew/opt/e2fsprogs/sbin:$PATH"' >> ~/.zshrc
21+
source ~/.zshrc
22+
```
23+
24+
### Intel (`/usr/local`)
25+
26+
```bash
27+
echo 'export PATH="/usr/local/opt/e2fsprogs/sbin:$PATH"' >> ~/.zshrc
28+
source ~/.zshrc
29+
```
30+
31+
## 3) Verify toolchain
32+
33+
```bash
34+
bun --version
35+
qemu-system-aarch64 --version || qemu-system-x86_64 --version
36+
mke2fs -V
37+
debugfs -V
38+
```
39+
40+
## 4) Install dependencies and validate
41+
42+
```bash
43+
bun install
44+
bun run test
45+
bun run typecheck
46+
bun run build
47+
```
48+
49+
## 5) Choose the build platform
50+
51+
Use a platform that matches the architecture you will run in Gondolin.
52+
53+
- Apple Silicon (`uname -m` => `arm64`): use `linux/arm64`
54+
- Intel Mac (`uname -m` => `x86_64`): use `linux/amd64`
55+
56+
`oci2gondolin` defaults automatically from host arch if `--platform` is omitted, but passing it explicitly is recommended.
57+
58+
Example:
59+
60+
```bash
61+
bun run oci2gondolin -- \
62+
--image busybox:latest \
63+
--platform linux/arm64 \
64+
--mode assets \
65+
--out ./out/busybox-assets
66+
```
67+
68+
## 6) Run integration + smoke checks
69+
70+
Apple Silicon:
71+
72+
```bash
73+
INTEGRATION_PLATFORM=linux/arm64 bun run test:integration
74+
PLATFORM=linux/arm64 bun run e2e:smoke
75+
```
76+
77+
Intel Mac:
78+
79+
```bash
80+
INTEGRATION_PLATFORM=linux/amd64 bun run test:integration
81+
PLATFORM=linux/amd64 bun run e2e:smoke
82+
```
83+
84+
## Troubleshooting
85+
86+
### `mke2fs` / `debugfs` not found
87+
88+
Confirm PATH includes the `e2fsprogs` `sbin` directory shown above.
89+
90+
### Case-sensitive filename conflicts during conversion
91+
92+
Some images include paths that conflict on case-insensitive filesystems.
93+
94+
Use a case-sensitive APFS location for temporary work/output (for example, a case-sensitive volume) and retry.

0 commit comments

Comments
 (0)