mirror of
https://github.com/marcoallegretti/karapace.git
synced 2026-03-26 21:43:09 +00:00
e6e0f3dd6d
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.
130 lines
3.8 KiB
Markdown
130 lines
3.8 KiB
Markdown
# Karapace
|
|
|
|
[](https://github.com/marcoallegretti/karapace/actions/workflows/ci.yml)
|
|
[](LICENSE)
|
|
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cargo install --git https://github.com/marcoallegretti/karapace.git karapace-cli
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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
|
|
|
|
- [Architecture](docs/architecture.md)
|
|
- [CLI Reference](docs/cli-reference.md)
|
|
- [Storage Format](docs/storage-format.md)
|
|
- [Security Model](docs/security-model.md)
|
|
- [Build and Reproducibility](docs/build-and-reproducibility.md)
|
|
- [Contributing](docs/contributing.md)
|
|
|
|
## License
|
|
|
|
[EUPL-1.2](LICENSE)
|