87fc370541
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.
93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# 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 `.deb`s 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:
|
|
|
|
```bash
|
|
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`).
|