Skip to main content

CONTAINER IMAGE

The image ghcr.io/tuna-os/tacklebox contains the native tacklebox binary and its runtime tools, including Podman, bootc, and xorriso. It has the same commands and recipe format as the native binary. Its entrypoint is tacklebox: pass build, verify, or --help after the image name.

Choose an image​

Use :latest to try the current build from main. For CI, pin a published version tag (:vX.Y.Z or :X.Y.Z), a :sha-<short-commit> tag, or an image digest (@sha256:…). Version tags correspond to releases; SHA tags select a specific build. A digest pins the exact image content. Pin the recipe's OS image references too if you need repeatable inputs.

The examples use :latest; replace it with your chosen pin in CI:

export TBOX_IMAGE=ghcr.io/tuna-os/tacklebox:latest
podman run --rm "$TBOX_IMAGE" --help
# Docker uses the same entrypoint:
docker run --rm "$TBOX_IMAGE" --help

Host and mount requirements​

Media creation needs a Linux host and a rootful container runtime. Run Podman with sudo, or use a rootful Docker daemon. Rootless --privileged does not grant access to host loop devices or block devices. Docker Desktop on macOS or Windows runs in a VM; these USB commands do not expose a physical host disk through that VM.

Builds run privileged because they mount filesystems and launch privileged containers through the Podman inside the image. Use a trusted image and recipe on a dedicated build host or CI runner that lets containers run with privileges. Hosted CI environments that prohibit them cannot use this build path.

Container pathHost sourcePurpose
/workRecipe directory, read-onlyRecipe and local customization scripts
/outWritable output directoryISO, scratch files, and caches under --output-base
/var/lib/containersDedicated named volumeNested Podman's image storage across runs
/devHost device tree for buildsLoop devices and USB disks, including partition nodes
/run/udevHost udev data, read-only for USB buildsDevice metadata used during provisioning

You do not need to mount a Docker or Podman socket. Tacklebox calls the Podman inside the image; a Docker socket is not a replacement for its local image store. Keep that store separate from the host's Podman store. The named volume also keeps image storage outside the outer container's writable layer.

Builds need network access to pull OS images and any recipe downloads. The default container network is enough. You do not need to publish ports or use the host network. Private image pulls need credentials inside the container. For example, mount an auth file read-only and set REGISTRY_AUTH_FILE to its container path. The container does not inherit registry logins from the host.

Use container paths for recipe file references. The examples use /work as the current directory. Relative paths for customization resolve there. Keep /out on a local filesystem with room for unpacked OS images and scratch files. The initramfs-cache/ and squashfs-cache/ directories live under the output base; retain them between builds. Root normally owns the output files on the host.

Build a live ISO​

Create my-iso.json using the quick start, then run from the directory that holds the recipe:

mkdir -p out
sudo podman volume create tacklebox-storage
sudo podman run --rm --privileged \
-v /dev:/dev \
-v "$PWD:/work:ro" -w /work \
-v "$PWD/out:/out" \
-v tacklebox-storage:/var/lib/containers \
"$TBOX_IMAGE" build /work/my-iso.json --iso /out/myos.iso -b /out

For Docker, use the same mounts and arguments:

docker volume create tacklebox-storage
docker run --rm --privileged \
-v /dev:/dev \
-v "$PWD:/work:ro" -w /work \
-v "$PWD/out:/out" \
-v tacklebox-storage:/var/lib/containers \
"$TBOX_IMAGE" build /work/my-iso.json --iso /out/myos.iso -b /out

Tacklebox writes the ISO to out/myos.iso. To build an image of a disk, omit --iso /out/myos.iso; the result is out/tacklebox.img. On SELinux hosts, these privileged build containers run without label separation. Do not relabel /dev or the host's container storage with :Z.

Provision a USB disk​

This erases the selected disk. Identify the whole USB disk with lsblk -o NAME,SIZE,MODEL,TRAN,MOUNTPOINTS and unmount its partitions first. Replace /dev/sdX below with that disk, not a partition. The bind mount at /dev exposes nodes for new partitions inside the container.

sudo podman run --rm --privileged \
-v /dev:/dev -v /run/udev:/run/udev:ro \
-v "$PWD:/work:ro" -w /work \
-v "$PWD/out:/out" \
-v tacklebox-storage:/var/lib/containers \
"$TBOX_IMAGE" build /work/my-iso.json /dev/sdX -b /out

With Docker, replace sudo podman run with docker run. Both commands expose the host device tree: check the target carefully before you run them.

Verify an artifact​

To verify an ISO, you do not need privileges or access to devices:

podman run --rm -v "$PWD/out:/out:ro" \
"$TBOX_IMAGE" verify /out/myos.iso
docker run --rm -v "$PWD/out:/out:ro" \
"$TBOX_IMAGE" verify /out/myos.iso

On an SELinux host, add :Z to this dedicated output mount (:/out:ro,Z) if label enforcement blocks reads. Verification of a raw disk image needs loop devices and mounts:

sudo podman run --rm --privileged -v /dev:/dev \
-v "$PWD/out:/out:ro" "$TBOX_IMAGE" verify /out/tacklebox.img

Replace sudo podman run with docker run for Docker. Verification checks the structure of the media; it does not replace a boot test.