os-build/docs/architecture.md

Arcline OS — architecture

This is the foundation ("the wires") for Arcline OS: a hardened, Debian-derived operating system for people who run infrastructure. The landing page describes the product; this repository is how it gets built.

Design goals

1. Secure by default — hardened kernel, default-deny firewall, AppArmor, locked-down ssh. You opt in to exposure, never out.
2. Zero telemetry — no phone-home, no analytics, no cloud integration.
3. btrfs-native — snapshots and boot-to-snapshot rollback are built in.
4. Production-ready from first boot — observability pre-configured, tools pre-installed, everything documented.
5. Auditable — every script and config is plain text in this repo.

How a build flows

flowchart LR
    A[editions/* metadata] --> B[debootstrap<br/>Debian bookworm]
    B --> C[install edition<br/>packages.list]
    C --> D[apply overlays<br/>base + edition]
    D --> E[configure-system.sh<br/>in chroot]
    E --> F[rootfs .tar.xz]
    F --> G[grub-mkrescue + squashfs<br/>→ live ISO]
    E -.toolchain .debs.-> C

Pipeline stages live in scripts/:

Stage	Script	What it does
bootstrap	build-rootfs.sh	debootstrap minbase, apt sources, package install
overlay	apply-overlays.sh	copies overlays/base + overlays/<edition> into the rootfs
configure	configure-system.sh	runs in the chroot: hostname, locale, kernel cmdline, services, live-boot, toolchain
package	build-iso.sh	kernel + initramfs + squashfs → hybrid BIOS/UEFI ISO
image	build-image.sh	rootfs → bootable qcow2/raw disk image (via deploy-disk.sh)
deploy	deploy-disk.sh	partition → btrfs layout → copy rootfs → GRUB + fstab (shared by image + installer)
install	install.sh	scripted installer for a real disk (confirmation-gated)
orchestrate	build-edition.sh / Makefile	wire the above to make iso-<edition>

The source trees

Path	Role
editions/	per-edition manifests: package lists, kernel cmdline, fstab, metadata
overlays/	files that land in the image, organised as layered rootfs trees
scripts/	the build pipeline (all plain bash, readable top to bottom)
btrfs/, toolchain/, tests/, ci/	supporting subsystems
scripts/secureboot/	MOK key generation + boot-chain signing (optional)

There is no hidden magic: the Makefile is a thin wrapper, versions.mk / scripts/common.sh hold the single source of truth for versions and paths.

Zero telemetry, enforced

• No distro telemetry packages are installed (ubuntu-report, popularity-contest, snapd are never in a package list).
• apt automatic-update timers are masked in every edition's metadata.
• The firewall's output chain never initiates calls on its own.
• cloud-init is pointed only at the configured cloud datasource.
• The smoke tests (tests/smoke/verify-rootfs.sh) fail the build if telemetry artifacts are found.

What "the wires" now covers

The four original follow-up items are implemented:

1. Disk images — make image-<edition> produces bootable qcow2/raw images; the cloud edition ships as a qcow2 by default.
2. Installer — scripts/install.sh <device> installs to a real disk (explicit confirmation, reuses the deploy module).
3. Grafana/Loki/Promtail .debs — make vendor packages them so the full observability stack installs without upstream repos.
4. Secure boot — MOK-based signing (scripts/secureboot/), off by default, enabled with ARCLINE_SIGN=1.

Still on the horizon

• A signed Microsoft-KEK boot chain (only relevant for commercial distribution; the MOK path covers self-hosted use).
• ARM64 (arm64) as a first-class arch (one-line change in versions.mk).
• Boot-time verification tests for installed systems (the smoke tests cover the image contents, not a booted VM yet).