euri-iso/docs/building.md

title, layout, nav_order

title	layout	nav_order
Building	default	2

Building the ISO

The ISO is built with buildiso (from Artix artools package) plus a customized profile. There are two supported paths: Option A (container) for systems without pacman, and Option B (native) for pacman-based systems.

Option A: Build in a container (non-pacman distros — recommended)

No Artix/Arch needed. Works on Gentoo, Fedora, Debian — anything without pacman that has podman. This is the same path GitHub Actions CI uses.

# Build the image (installs artools + deps inside an Artix container)
podman build -t euri-build .

# Build the ISO (rootful podman required — artools chroots mount devtmpfs,
# which rootless containers cannot do)
sudo podman run --rm --privileged \
  -v /var/lib/artools-buildiso:/var/lib/artools/buildiso \
  -v "$(pwd)/iso-output:/workspace/iso-output" \
  -e WORKSPACE_DIR=/workspace \
  euri-build

Or use the helper script:

./build-iso-podman.sh

The finished .iso lands in iso-output/.

Option B: Native build (just pacman + artools)

You do not need an Artix-based system — buildiso is plain bash on top of pacman. You need:

• pacman (native on Arch/Artix/KaOS; on other distros, install it or extract the .pkg.tar.zst files)
• the artools libraries from the Artix repo: artools-base (provides basestrap, artix-chroot, fstabgen) and artools-iso (provides buildiso) plus their deps
• squashfs-tools, grub, xorriso/libisoburn, dosfstools, mtools

Prerequisites (native path)

# On Arch/Artix:
pacman -S artools squashfs-tools
modprobe loop

# On KaOS (pacman native, but artools not in KaOS repos — extract from Artix):
pacman -S squashfs-tools

# On other distros: grab artools-base/artools-iso from the Artix repo and
# extract them over /, then install pacman and the deps listed above.

squashfs-tools is needed for mksquashfs. The loop module must be loaded for mount -o loop during image assembly.

Clone and configure

git clone https://antergos-nas.taild4360b.ts.net/Euri-Linux/euri-iso.git
cd euri-iso

export WORKSPACE_DIR="$PWD"

# Override pacman config with our repo (euri-pkgs)
mkdir -p ~/.config/artools/pacman.conf.d
cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/

Without this override, buildiso uses /usr/share/artools/pacman.conf.d/iso-x86_64.conf (from the artools package), which lacks the [euri-pkgs] repository. The build will then try to fetch our custom packages (branding, Calamares config, wallpapers) from Artix repos and fail.

Build

sudo -E ./buildiso -p euri

• Use ./buildiso, not buildiso. The system /usr/bin/buildiso lacks --overwrite='*', which causes file conflicts between calamares and calamares-branding-euri (both claim /usr/share/calamares/branding/default/). Our repo's ./buildiso has it.
• sudo -E is required. Without -E, WORKSPACE_DIR is stripped and load_profile() returns empty HAS_LIVE/LIVEUSER, causing the build to fail early.

Output

The ISO appears in /var/lib/artools/buildiso/iso/euri/:

/var/lib/artools/buildiso/iso/euri/
├── euri-<date>.iso       # Bootable ISO
└── euri-<date>.sha1sum   # Checksum

First build pulls ~5 GB from the internet (package downloads). Subsequent builds use pacman cache.

Environment variables

Variable	Purpose
WORKSPACE_DIR	Must point to repo root. buildiso looks for profiles under $WORKSPACE_DIR/iso-profiles/
COMPRESSION	Squashfs compression type (e.g. zstd, gzip, xz). If unset, mksquashfs produces a zero-size sparse file instead of a valid squashfs

Troubleshooting

"File conflict" errors during build

This means --overwrite='*' is not being passed to basestrap. Make sure you're using the repo's ./buildiso, not the system one:

# Wrong — system buildiso without --overwrite:
buildiso -p euri

# Correct:
./buildiso -p euri

Build fails with "HAS_LIVE is empty"

Forgetting sudo -E:

# Wrong — WORKSPACE_DIR not preserved:
sudo ./buildiso -p euri

# Correct:
sudo -E ./buildiso -p euri

buildiso can't find our custom repo

The pacman config override is missing:

mkdir -p ~/.config/artools/pacman.conf.d
cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/

Zero-size squashfs (ISO exists but is tiny)

$COMPRESSION is unset. Either set it in profile.yaml or pass it via environment:

export COMPRESSION=zstd
sudo -E ./buildiso -p euri

Remove the stale image before retrying:

rm -rf /var/lib/artools/buildiso/iso/euri/

Corrupted pacman cache

If basestrap fails with checksum errors, clear the cache:

rm -rf /var/lib/artools/buildiso/pkg/euri/cache/

Then rebuild.

Which option do I use?

• Arch / Artix / KaOS / any pacman-based distro → Option B (native).
• Anything else (Gentoo, Fedora, Debian, ...) → Option A (podman).

CI builds

The CI pipeline (.github/workflows/build.yml) handles all of the above automatically. It runs in an Artix container, sets WORKSPACE_DIR, overrides pacman config, mounts a 12 GB tmpfs, and builds the ISO. It also runs the AI community moderator on issues/PRs (.github/workflows/ai-moderator.yml).

An Internet Archive upload step exists in the workflow but is currently disabled (if: false) — builds are manually verified first. When enabled it uploads with identifier euri-YYYYMMDD-<run_number>.

Trigger CI manually from the GitHub Actions tab (push trigger is disabled).

Local pacman repo

To use the custom packages repo on an installed system:

[euri-pkgs]
SigLevel = Optional TrustAll
Server = https://antergos-nas.taild4360b.ts.net/pkgs