79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# os/ — the narOS build tree
|
|
|
|
This directory builds **narOS** (the Nucleic Agent Runtime OS) per
|
|
[docs/NAROS.md](../docs/NAROS.md): a Debian-trixie-derived rootfs assembled from scratch
|
|
with `mmdebstrap` against a pinned `snapshot.debian.org` date, plus a Nucleic apt package
|
|
layer (nash, naros-init, tier meta-packages, …). CI (`.github/workflows/naros.yml`)
|
|
publishes OCI images to GHCR (`naros-base`, later `naros-agent`/`naros-runner`) and the
|
|
signed apt repository to Cloudflare R2.
|
|
|
|
## Layout
|
|
|
|
```
|
|
VERSION # the narOS release version (26.MM[.p]) — single source of truth
|
|
SNAPSHOT # pinned snapshot.debian.org timestamp for this release
|
|
mkimage/
|
|
build-rootfs.sh # mmdebstrap driver: <tier> <arch> → rootfs tar (needs root/unshare)
|
|
hooks/00-identity.sh # writes /etc/os-release (ID=naros) + /etc/naros/{manifest.json,…}
|
|
profiles/<tier>.pkgs # Debian package list per tier
|
|
profiles/<tier>.naros-pkgs # Nucleic packages per tier (installed when a pool is supplied)
|
|
packages/
|
|
build-all.sh # builds every package below into dist/pool/ with dpkg-deb
|
|
<name>/control # control template (@VERSION@/@ARCH@ substituted)
|
|
<name>/files/ # static payload, copied verbatim
|
|
<name>/stage.sh # optional dynamic staging (e.g. install a prebuilt binary)
|
|
<name>/postinst,prerm # optional maintainer scripts
|
|
repo/
|
|
publish.sh # dist/pool → apt tree (dists/<channel>/…), signs when a key is present
|
|
r2-sync.sh # pushes the apt tree to Cloudflare R2 (CI; needs credentials)
|
|
images/
|
|
agent/ # naros-agent OCI layer FROM naros-base (Dockerfile + build.sh):
|
|
# naros-tier-agent (apt), Node 22, rustup, Go, mise, warm
|
|
# caches, agent user (uid 501), agent CLIs, Playwright
|
|
tests/
|
|
parity-sweep.sh # tool-inventory diff vs the previous default sandbox image
|
|
dist/ # build output (gitignored): bin/, pool/, repo/, rootfs tars
|
|
```
|
|
|
|
## Building
|
|
|
|
Packages (any Debian-family host, no root needed):
|
|
|
|
```sh
|
|
os/packages/build-all.sh --arch arm64,amd64 # expects prebuilt nash/naros-init in
|
|
# os/dist/bin/<name>-<arch> (see below)
|
|
```
|
|
|
|
Prebuilt binaries: `nash` and `naros-init` are Rust (musl-static, built from `shell/`);
|
|
CI drops them at `os/dist/bin/nash-{arm64,amd64}` and `os/dist/bin/naros-init-{arm64,amd64}`.
|
|
Locally: `cargo build --release -p nash -p naros-init` (with the musl targets) and copy.
|
|
Packages whose binary is missing are skipped with a warning, so pure-metadata iteration
|
|
works without a Rust toolchain.
|
|
|
|
Rootfs (needs mmdebstrap; root or unshare-capable user — CI, or a root container):
|
|
|
|
```sh
|
|
os/mkimage/build-rootfs.sh base arm64 --pool os/dist/pool
|
|
docker import os/dist/naros-base-<ver>-arm64.tar naros-base:test
|
|
docker run --rm naros-base:test sh -c '. /etc/os-release && echo "$ID $VERSION_ID"'
|
|
```
|
|
|
|
Without `--pool`, the build produces a plain identity-only base (no Nucleic packages) —
|
|
useful for validating the mmdebstrap/snapshot/identity plumbing in isolation.
|
|
|
|
Agent tier (needs docker; the agent tier is an OCI **layer** on naros-base, not a
|
|
separate mmdebstrap run, so pulls dedupe on the shared base):
|
|
|
|
```sh
|
|
docker import os/dist/naros-base-<ver>-arm64.tar naros-base:local
|
|
os/images/agent/build.sh arm64 --base naros-base:local
|
|
docker run --rm naros-agent:build-arm64 nash -lc 'naros info'
|
|
```
|
|
|
|
## Versioning
|
|
|
|
`VERSION` + `SNAPSHOT` define a release (NAROS.md §8). Channels: `edge` (weekly CI,
|
|
fresh snapshot) and `stable` (promoted deliberately; what `ProjectSandbox.defaultImage`
|
|
pins). Nucleic packages carry their own versions in `packages/<name>/VERSION` (falling
|
|
back to 0.1.0), suffixed with the channel.
|