mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00

Marco Allegretti e6e0f3dd6d docs: rewrite all documentation from source code

Delete 14 old docs files (AI-generated, riddled with Phase/M1/1.0
jargon, references to non-existent commands, stale CI snippets).

New documentation (6 files), written from repository source analysis:
- docs/architecture.md — crate graph, engine lifecycle, identity
  computation, runtime backends, store design, WAL, GC, unsafe blocks
- docs/cli-reference.md — all 23 commands with syntax, args, flags,
  exit codes, env vars, verified against crates/karapace-cli/src/main.rs
- docs/storage-format.md — directory layout, objects, layers, metadata,
  manifest format, lock file, WAL, atomic write contract
- docs/security-model.md — mount/device/env var policies with exact
  defaults from security.rs, trust assumptions, what is NOT protected
- docs/build-and-reproducibility.md — CI env vars, RUSTFLAGS, cargo
  profile, reproducibility verification, toolchain pinning
- docs/contributing.md — setup, verification, project layout, code
  standards, testing, CI workflows

README.md rewritten: concise, no marketing language, prerequisites
first, usage example, command table, limitations section.

CONTRIBUTING.md now points to docs/contributing.md.
CHANGELOG.md cleaned: removed M1-M8 labels, Phase refs, stale counts.

2026-02-23 01:25:07 +01:00

3.2 KiB

Raw Blame History

Build and Reproducibility

Deterministic identity

The environment identity (env_id) is a blake3 hash computed from the fully resolved lock file — not from the unresolved manifest. Two identical lock files on any machine produce the same env_id.

The identity is computed in karapace-schema/src/lock.rs::LockFile::compute_identity(). See architecture.md for the full list of hash inputs.

Lock file

karapace build writes karapace.lock next to the manifest. This file pins:

Base image content digest (blake3 of rootfs)
Exact package versions (queried from the package manager inside the image)
All manifest-declared settings (hardware, mounts, backend, resource limits)

The lock file should be committed to version control.

Reproducibility constraints

Given the same lock file and the same base image content, builds produce the same env_id. The overlay filesystem content depends on the package manager's behavior, which Karapace does not control.

Karapace guarantees identity reproducibility (same inputs → same env_id). It does not guarantee bit-for-bit filesystem reproducibility across different package repository states.

CI release builds

Configured in .github/workflows/ci.yml and .github/workflows/release.yml.

Environment variables

Variable	Value	Purpose
`CARGO_INCREMENTAL`	`0`	Disable incremental compilation
`SOURCE_DATE_EPOCH`	`0`	Deterministic timestamps in build artifacts

RUSTFLAGS

-D warnings
--remap-path-prefix /home/runner/work=src
--remap-path-prefix /home/runner/.cargo/registry/src=crate
--remap-path-prefix /home/runner/.rustup=rustup

Path remapping eliminates runner-specific filesystem paths from the binary.

Cargo profile (release)

Defined in workspace Cargo.toml:

[profile.release]
strip = true
lto = "thin"

Build procedure

cargo clean — eliminates stale intermediate artifacts
cargo build --release --target <target> -p karapace-cli -p karapace-dbus

Both glibc (x86_64-unknown-linux-gnu) and musl (x86_64-unknown-linux-musl) targets are built. Musl binaries are fully statically linked.

Reproducibility verification in CI

CI runs two types of reproducibility checks:

Same-run: two sequential builds on the same runner, output hashes compared
Cross-run: builds on ubuntu-latest and ubuntu-22.04, hashes compared (warning-only — different system libraries may cause differences in glibc builds)

Musl builds are expected to be runner-independent.

Constraint: build invocations must use identical -p flags. Building -p karapace-cli alone may produce a different binary than -p karapace-cli -p karapace-dbus due to codegen unit ordering.

Local development builds

.cargo/config.toml configures path remapping for the project maintainer. Other developers should update the paths or set RUSTFLAGS directly.

Local builds are for development. CI builds are the authoritative release artifacts.

Pinned toolchain

CI pins Rust toolchain version via RUST_TOOLCHAIN environment variable (currently 1.93). This is set in the workflow env block and used with dtolnay/rust-toolchain@stable.

3.2 KiB Raw Blame History