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.
86 lines
3.8 KiB
Markdown
86 lines
3.8 KiB
Markdown
# Arcline OS — build system
|
|
|
|
> The Linux OS for people who run infrastructure. Hardened Debian base.
|
|
> Pre-configured monitoring, auditing, and security tooling. Zero telemetry.
|
|
|
|
This repository is the build system ("the wires") behind
|
|
[Arcline OS](https://arcline.it). It turns a Debian base and a set of plain-text
|
|
manifests into hardened, bootable operating system images for three editions:
|
|
**Server**, **Workstation**, and **Cloud**.
|
|
|
|
## What you get
|
|
|
|
- A transparent, script-based build pipeline (no magic, everything auditable)
|
|
- `debootstrap` → package install → overlay → in-chroot configure → live ISO
|
|
- **Secure by default**: hardened kernel cmdline + sysctl, default-deny
|
|
nftables, key-only ssh, AppArmor, no core dumps
|
|
- **btrfs-native**: subvolume layout, scheduled read-only snapshots, and
|
|
boot-to-snapshot rollback tooling
|
|
- **Zero telemetry**: enforced by package selection, masked apt timers, and
|
|
smoke tests that fail the build if telemetry is found
|
|
- **Pre-configured observability** (server): Prometheus + node_exporter +
|
|
Grafana (auto-provisioned) + Loki + promtail, local-only
|
|
- **The Arcline toolchain**: a harness that packages all 11 Go tools into
|
|
`.deb`s and installs them into the image
|
|
- Smoke tests, GitLab CI, and docs that explain every decision
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# on a Debian-family host with root/sudo
|
|
make deps # install host build dependencies
|
|
make check # validate the tree (fast, offline)
|
|
make iso-server # build a bootable server ISO
|
|
make iso # build all three editions
|
|
make toolchain # build the 11 Go tools into .deb
|
|
make iso-server-minimal # server ISO WITHOUT the Arcline toolchain
|
|
make test # run smoke tests against built rootfs(es)
|
|
```
|
|
|
|
Artifacts land in `build/artifacts/` with `.sha256` checksums.
|
|
|
|
The Arcline tools are **optional** in an image (`ARCLINE_TOOLCHAIN=auto|skip|
|
|
require`; see [building](docs/building.md#building-without-the-arcline-toolchain)).
|
|
|
|
## Layout
|
|
|
|
```
|
|
os-build/
|
|
├── Makefile # thin orchestration (make iso-<edition>)
|
|
├── versions.mk # single source of truth for versions/paths
|
|
├── editions/ # per-edition manifests (packages, cmdline, fstab, metadata)
|
|
├── overlays/ # files that land in the image (base + per-edition layers)
|
|
├── scripts/ # the build pipeline (all plain bash)
|
|
├── btrfs/ # subvolume layout, snapshots, rollback
|
|
├── toolchain/ # packaging for the 11 Go tools
|
|
├── observability/ # Prometheus/Grafana/Loki configs (docs + overlays/server)
|
|
├── tests/ # tree validation + rootfs smoke tests
|
|
├── ci/ # GitLab CI pipeline
|
|
└── docs/ # architecture, hardening, building, editions, ...
|
|
```
|
|
|
|
## Documentation
|
|
|
|
| Doc | Contents |
|
|
|-----|----------|
|
|
| [architecture](docs/architecture.md) | the design and how a build flows |
|
|
| [building](docs/building.md) | prerequisites, quickstart, outputs, knobs |
|
|
| [hardening](docs/hardening.md) | every hardening decision, and how to tune it |
|
|
| [editions](docs/editions.md) | server / workstation / cloud manifests |
|
|
| [observability](docs/observability.md) | the pre-configured monitoring stack |
|
|
| [toolchain](docs/toolchain.md) | the 11 Go tools and their packaging |
|
|
| [btrfs](btrfs/README.md) | subvolume layout + snapshots + rollback |
|
|
|
|
## Status
|
|
|
|
This is the **foundation**: the build pipeline, edition manifests, hardening
|
|
baseline, btrfs tooling, observability configs, tests, and CI are in place and
|
|
runnable. The next milestones (installer that writes the btrfs layout to disk,
|
|
cloud disk images, signed releases) are listed in
|
|
[docs/architecture.md](docs/architecture.md#follow-up-work).
|
|
|
|
## License
|
|
|
|
GPL-3.0 — see [LICENSE](LICENSE). Sponsored by Arcline IT LLC.
|
|
No telemetry. No tracking.
|