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.0 KiB

Raw Blame History

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

Secure by default — hardened kernel, default-deny firewall, AppArmor, locked-down ssh. You opt in to exposure, never out.
Zero telemetry — no phone-home, no analytics, no cloud integration.
btrfs-native — snapshots and boot-to-snapshot rollback are built in.
Production-ready from first boot — observability pre-configured, tools pre-installed, everything documented.
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
orchestrate	`build-edition.sh` / `Makefile`	wire the above to `make iso-<edition>`

The four 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/`, `observability/`, `tests/`, `ci/`	supporting subsystems

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.

Follow-up work (explicitly out of scope for "the wires")

Partitioning/installer that runs btrfs/init.sh on a target disk.
Cloud images (qcow2/raw) for the cloud edition — the ISO path is wired, a disk-image path is the next step.
Grafana/Loki packaged as .debs rather than fetched from upstream.
A signed (secure-boot) kernel for official releases.

3.0 KiB Raw Blame History