marcoallegretti/karapace
1
0
Fork 0
mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
karapace/docs/architecture.md
Marco Allegretti 5306963cce docs: comprehensive public documentation 
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 18:38:41 +01:00

4.5 KiB
Raw Blame History

Karapace Architecture

Overview

Karapace is a deterministic container environment engine organized as a Cargo workspace of 9 crates. Each crate has a single responsibility and clean dependency boundaries.

Crate Dependency Graph

karapace-cli ─────┬──▶ karapace-core ──┬──▶ karapace-schema
                  │                    ├──▶ karapace-store
                  │                    ├──▶ karapace-runtime
                  │                    └──▶ karapace-remote
                  ├──▶ karapace-remote ──▶ karapace-store
                  └──▶ karapace-tui ────▶ karapace-core

karapace-dbus ────────▶ karapace-core
karapace-server ──────▶ karapace-store (standalone HTTP server)

Crate Responsibilities

karapace-schema

Manifest v1 parsing (TOML), normalization, canonical JSON serialization, environment identity hashing, lock file v2 (resolved packages, integrity/intent verification), and built-in presets.

karapace-store

Content-addressable object store (blake3), layer manifests, environment metadata (with naming, ref-counting, state machine), garbage collection with signal cancellation, and store integrity verification. All writes are atomic via NamedTempFile + persist.

karapace-runtime

Container runtime abstraction (RuntimeBackend trait) with three backends:

  • Namespace — unshare + fuse-overlayfs + chroot (unprivileged)
  • OCI — crun/runc/youki
  • Mock — deterministic test backend

Also handles image downloading, sandbox scripting, host integration (Wayland, GPU, audio, D-Bus), security policy enforcement, and desktop app export.

karapace-core

The Engine struct orchestrates the full lifecycle: init → resolve → lock → build → enter/exec → freeze → archive → destroy. Caches MetadataStore, ObjectStore, and LayerStore as fields. Handles drift detection (diff/commit/export via overlay upper_dir scanning) and garbage collection delegation.

karapace-cli

23 CLI commands, each in its own file under commands/. Shared helpers in commands/mod.rs (spinners, colored output, environment resolution, JSON formatting). main.rs is a thin dispatcher. Exit codes: 0 (success), 1 (failure), 2 (manifest error), 3 (store error).

karapace-dbus

Socket-activated D-Bus service (org.karapace.Manager1) with 11 methods. Typed serde response structs. Desktop notifications via notify-rust. 30-second idle timeout for socket activation. Hardened systemd unit file.

karapace-remote

Remote content-addressable store with RemoteBackend trait, HTTP backend (ureq), push/pull transfer with blake3 integrity verification on pull, and a JSON registry for name@tag references.

karapace-tui

Interactive terminal UI (ratatui + crossterm) with list/detail/help views, vim-style keybindings, search/filter, sort cycling, freeze/archive/rename actions, and confirmation dialogs.

Key Design Decisions

  1. Content-addressed identity — env_id is computed from the resolved lock file (pinned versions + base image content digest), not from unresolved manifest data.

  2. Atomic operations — All store writes use NamedTempFile + persist for crash safety. Rebuild builds the new environment before destroying the old one.

  3. No unwrap() in production — All error paths are handled with proper error types (StoreError, CoreError, RemoteError, RuntimeError).

  4. Store locking — StoreLock file lock on all mutating operations (CLI + D-Bus). GC respects active/archived environments.

  5. Layered security — Mount whitelist, device policy, env var allow/deny, resource limits. No privilege escalation.

Data Flow

Manifest (TOML)
    │
    ▼
NormalizedManifest (canonical JSON)
    │
    ▼ resolve (RuntimeBackend)
ResolutionResult (base_image_digest + resolved_packages)
    │
    ▼
LockFile v2 (pinned, verifiable)
    │
    ▼ compute_identity()
EnvIdentity (env_id = blake3 of canonical lock)
    │
    ▼ build (store objects + layers + metadata)
Built Environment (overlay filesystem)

karapace-server

Reference remote server implementing protocol v1 over HTTP (tiny_http). Provides blob storage, registry, and list endpoints. Used for testing push/pull workflows.

Test Coverage

417 tests across all crates. 24 ignored tests require privileged operations (real unshare, fuse-overlayfs, ENOSPC simulation, namespace access).