Files

Blake Ridgway 87fc370541 docs: add architecture, hardening, and building documentation

Document the design and how to operate it: architecture, building
(including toolchain-free/minimal builds), hardening guide, editions,
observability, and the toolchain. README ties it together.

2026-08-21 13:15:43 -05:00

3.3 KiB

Raw Blame History

Building Arcline OS

Prerequisites

A Debian-family host (or container) with root/sudo:

debootstrap        # rootfs bootstrap
squashfs-tools     # ISO rootfs compression
grub2-common       # grub-mkrescue (hybrid ISO)
xorriso cpio       # ISO assembly
bash make curl git # build orchestration
go (≥ 1.21)        # only needed for `make toolchain`

Check or install them:

scripts/check-host-deps.sh            # report what's missing
scripts/check-host-deps.sh --install  # apt-get install the missing bits

Quickstart

make check          # validate the tree (fast, offline, safe)
make rootfs-server  # build just the server rootfs
make iso-server     # build a bootable server ISO
make iso            # build all three editions
make toolchain      # build the 11 Go tools into .deb
make test           # run smoke tests against built rootfs(es)

Outputs

Everything lands under build/:

Path	Contents
`build/rootfs/<edition>/`	extracted rootfs (from `make rootfs-*`)
`build/artifacts/arcline-<edition>-<version>-<arch>.tar.xz`	archived rootfs
`build/artifacts/arcline-<edition>-<version>-<arch>.iso`	bootable live ISO
`build/debs/*.deb`	Arcline toolchain packages (from `make toolchain`)

Each artifact ships with a .sha256 checksum file.

Reproducibility knobs

Set these as environment variables or edit versions.mk:

Variable	Meaning	Default
`VERSION`	release version string	`0.1.0`
`DEBIAN_SUITE`	Debian base	`bookworm`
`ARCH`	target architecture	`amd64`
`DEBIAN_MIRROR`	mirror for the base	`http://deb.debian.org/debian`
`ARCLINE_LIVE`	install live-boot into rootfs	unset (set by ISO build)
`ARCLINE_LOCK_ROOT`	lock root account (`passwd -l root`)	`0`
`ARCLINE_EXTRA_REPOS`	fetch grafana/loki upstream repos	`0`
`ARCLINE_TOOLCHAIN`	toolchain in image builds	`auto`

Building without the Arcline toolchain

The 11 Go tools (see docs/toolchain.md) are optional in an image — a normal make iso-server with no .debs in build/debs/ already produces a minimal, toolchain-free image. This is controlled by ARCLINE_TOOLCHAIN:

Mode	Behaviour
`auto` (default)	install the tools if `build/debs/*.deb` exist, otherwise build without them (with a warning)
`skip`	never install the tools, even if debs are present
`require`	fail the build if no toolchain debs are available

Examples:

make iso-server                # auto: tools in if you ran `make toolchain`
make iso-server-minimal        # skip: guaranteed toolchain-free image
ARCLINE_TOOLCHAIN=skip make iso-server
ARCLINE_TOOLCHAIN=require make iso-server   # release builds must ship the tools

Everything else — hardened base, firewall, btrfs, observability (Prometheus/node_exporter are Debian-main packages), zero-telemetry — is independent of the toolchain and always included.

Notes on the ISO

The ISO boots a live system (via live-boot): the rootfs is compressed to a squashfs and mounted on boot, so you can try an edition before installing it to disk. The same rootfs can be installed with the btrfs layout via btrfs/init.sh (the installer is follow-up work — see docs/architecture.md).

3.3 KiB Raw Blame History