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/README.md
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.8 KiB
Raw Blame History

Karapace

CI License: EUPL-1.2

Deterministic, content-addressed container environments for Linux. No root. No daemon.

Karapace builds isolated development environments from declarative TOML manifests using Linux user namespaces and overlay filesystems. Each environment gets a unique identity (blake3 hash) derived from its fully resolved dependencies.

Prerequisites

  • Linux with user namespaces (CONFIG_USER_NS=y)
  • fuse-overlayfs
  • curl
  • Optional: crun/runc/youki (OCI backend)

Run karapace doctor to check.

Install

git clone https://github.com/marcoallegretti/karapace.git
cd karapace
cargo build --release
sudo install -Dm755 target/release/karapace /usr/local/bin/karapace

Or via cargo:

cargo install --git https://github.com/marcoallegretti/karapace.git karapace-cli

Usage

# Create a manifest
cat > karapace.toml << 'EOF'
manifest_version = 1

[base]
image = "rolling"

[system]
packages = ["git", "curl"]

[runtime]
backend = "namespace"
EOF

# Build and enter
karapace build
karapace enter <env_id>

# Run a command
karapace exec <env_id> -- git --version

# Snapshot
karapace commit <env_id>
karapace restore <env_id> <snapshot_hash>

See examples/ for more manifests: minimal.toml, dev.toml, gui-dev.toml, ubuntu-dev.toml, rust-dev.toml.

Commands

23 commands. All accept --json, --store <path>, --verbose, --trace.

build [manifest] [--name]       Build environment
rebuild [manifest] [--name]     Destroy + rebuild
enter <id> [-- cmd...]          Enter environment
exec <id> -- <cmd...>           Run command in environment
destroy <id>                    Destroy environment
stop <id>                       Stop running environment
freeze <id>                     Freeze (prevent writes)
archive <id>                    Archive (prevent entry)
list                            List environments
inspect <id>                    Show metadata
diff <id>                       Show overlay changes
snapshots <id>                  List snapshots
commit <id>                     Snapshot overlay
restore <id> <hash>             Restore snapshot
gc [--dry-run]                  Garbage collect
verify-store                    Check store integrity
push <id> [--tag] [--remote]    Push to remote
pull <ref> [--remote]           Pull from remote
rename <id> <name>              Rename environment
doctor                          Check prerequisites
migrate                         Check store version
completions <shell>             Shell completions
man-pages [dir]                 Generate man pages

Workspace

9 crates:

karapace-schema     Manifest, normalization, lock file, identity
karapace-store      Objects, layers, metadata, WAL, GC, integrity
karapace-runtime    Backends (namespace/oci/mock), images, security
karapace-core       Engine: lifecycle orchestration
karapace-cli        CLI (23 commands)
karapace-dbus       D-Bus service (optional)
karapace-tui        Terminal UI (optional)
karapace-remote     Remote store client, push/pull
karapace-server     Reference HTTP server

Limitations

  • Linux only.
  • Layer packing drops: extended attributes, device nodes, hardlinks, SELinux labels, ACLs.
  • Base images are content-hashed but not GPG-verified.
  • No MAC enforcement (SELinux/AppArmor) inside containers.
  • Remote protocol has no authentication yet.

Documentation

License

EUPL-1.2