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

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

2.8 KiB

Raw Blame History

Karapace Manifest v0.1 Specification

Overview

The Karapace manifest is a TOML file (typically karapace.toml) that declaratively defines an environment. It is the single source of truth for environment identity.

Schema

Required Fields

Field	Type	Description
`manifest_version`	`u32`	Must be `1`.
`base.image`	`string`	Base image identifier. Must not be empty.

Optional Sections

`[system]`

Field	Type	Default	Description
`packages`	`string[]`	`[]`	System packages to install. Duplicates are deduplicated during normalization.

`[gui]`

Field	Type	Default	Description
`apps`	`string[]`	`[]`	GUI applications to install.

`[hardware]`

Field	Type	Default	Description
`gpu`	`bool`	`false`	Request GPU passthrough (`/dev/dri`).
`audio`	`bool`	`false`	Request audio device passthrough (`/dev/snd`).

`[mounts]`

Flat key-value pairs. Each key is a label; each value is <host_path>:<container_path>.

Labels must not be empty.
The : separator is required.
Absolute host paths are validated against the mount whitelist.
Relative host paths (e.g. ./) are always permitted.

`[runtime]`

Field	Type	Default	Description
`backend`	`string`	`"namespace"`	Runtime backend: `namespace`, `oci`, or `mock`.
`network_isolation`	`bool`	`false`	Isolate network from host.

`[runtime.resource_limits]`

Field	Type	Default	Description
`cpu_shares`	`u64?`	`null`	CPU shares limit.
`memory_limit_mb`	`u64?`	`null`	Memory limit in MB.

Validation Rules

manifest_version must equal 1.
Unknown fields at any level cause a parse error (deny_unknown_fields).
base.image must not be empty or whitespace-only.
Mount specs must contain exactly one : with non-empty sides.

Normalization

During normalization:

All string values are trimmed.
system.packages and gui.apps are sorted, deduplicated.
Mounts are sorted by label.
runtime.backend is lowercased.

The normalized form is serialized to canonical JSON for hashing.

Example

manifest_version = 1

[base]
image = "rolling"

[system]
packages = ["clang", "cmake", "git"]

[gui]
apps = ["ide", "debugger"]

[hardware]
gpu = true
audio = true

[mounts]
workspace = "./:/workspace"

[runtime]
backend = "namespace"
network_isolation = false

[runtime.resource_limits]
cpu_shares = 1024
memory_limit_mb = 4096

Versioning

The manifest format is versioned via manifest_version.
Only version 1 is supported in Karapace 0.1.
Future versions will increment this field.
Backward-incompatible changes require a version bump.

2.8 KiB Raw Blame History