diff --git a/README.md b/README.md index 60f2fc5..83ac856 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,10 @@ karapace commit karapace restore ``` +![Create a manifest](docs/imgs/Screenshot_20260225_105438.png) + +![Build and inspect an environment](docs/imgs/Screenshot_20260225_110322.png) + See `examples/` for more manifests: `minimal.toml`, `dev.toml`, `gui-dev.toml`, `ubuntu-dev.toml`, `rust-dev.toml`. ## Commands @@ -120,6 +124,7 @@ karapace-server Reference HTTP server ## Documentation +- [Getting Started](docs/getting-started.md) - [Architecture](docs/architecture.md) - [CLI Reference](docs/cli-reference.md) - [Storage Format](docs/storage-format.md) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..f8a6ed4 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,199 @@ +# Getting Started + +This tutorial walks through the first commands you typically use with Karapace. + +It is written as a hands-on sequence: + +1. Create a `karapace.toml` manifest. +2. Pin the base image reference. +3. Build an environment (produces an `env_id`). +4. Inspect and run commands inside the environment. +5. Save and restore filesystem changes with snapshots. + +For full command flags and exit codes, see [cli-reference.md](cli-reference.md). + +## Prerequisites + +- A Linux host. +- Runtime prerequisites must be available on your machine (user namespaces, overlay tooling, etc.). + +You can validate prerequisites and store health with: + +```bash +karapace doctor +``` + +If you are building the CLI from source, the binary is `karapace` (crate `karapace-cli`). + +## Choose a store location + +Karapace keeps all persistent data in a *store directory*. + +- Default store path: `~/.local/share/karapace` +- Override per-command with `--store ` + +In this tutorial, we use a disposable store directory so you can experiment safely: + +```bash +STORE="$(mktemp -d /tmp/karapace-store.XXXXXX)" +``` + +## 1) Create a manifest (`karapace new`) + +Create a new `karapace.toml` in an empty project directory: + +```bash +mkdir -p my-project +cd my-project + +karapace --store "$STORE" new demo --template minimal +``` + +What this does: + +- Writes `./karapace.toml` in the current directory. +- If your terminal is interactive (TTY), the command may prompt for optional fields: + - Packages (space-separated) + - A workspace mount + - Runtime backend (`namespace`, `oci`, `mock`) + - Network isolation + +What to expect: + +- On success, it prints that `karapace.toml` was written. +- If `./karapace.toml` already exists: + - With `--force`, it overwrites. + - Without `--force`, it prompts on a TTY; otherwise it fails. + +## 2) Pin the base image (`karapace pin`) + +Many workflows rely on using a pinned base image reference. + +Check whether the manifest is already pinned: + +```bash +karapace --store "$STORE" pin --check karapace.toml +``` + +What to expect: + +- On a fresh `minimal` template, `pin --check` typically fails with an error indicating `base.image` is not pinned. + +Pin the base image in-place: + +```bash +karapace --store "$STORE" pin karapace.toml +``` + +Then re-check: + +```bash +karapace --store "$STORE" pin --check karapace.toml +``` + +What this does: + +- Resolves the `base.image` value to an explicit `http(s)://...` URL. +- Rewrites the manifest file atomically. + +## 3) Build an environment (`karapace build`) + +Build an environment from the manifest: + +```bash +karapace --store "$STORE" build --require-pinned-image karapace.toml +``` + +What this does: + +- Resolves and prepares the base image. +- Builds the environment filesystem. +- Writes `karapace.lock` next to the manifest. +- Produces a deterministic `env_id` (a 64-character hex string). The first 12 characters are the `short_id`. + +What to expect: + +- The first build for a base image may download and extract a root filesystem. +- On success, output includes the `env_id`. + +## 4) Discover and inspect environments (`list`, `inspect`) + +List environments in the store: + +```bash +karapace --store "$STORE" list +``` + +Inspect a specific environment: + +```bash +karapace --store "$STORE" inspect +``` + +What to expect: + +- `list` shows `SHORT_ID`, `NAME`, `STATE`, and `ENV_ID`. +- After a build, the state is typically `built`. + +## 5) Run a command inside the environment (`exec`) + +Run a non-interactive command inside an environment: + +```bash +karapace --store "$STORE" exec -- sh -lc "echo hello" +``` + +What this does: + +- Transitions the environment to `Running` for the duration of the command. +- Streams stdout/stderr back to your terminal. +- Returns to `Built` when the command finishes. + +## 6) Check filesystem drift (`diff`) + +If you write to the environment, those changes live in the writable overlay. + +Show changes in the overlay: + +```bash +karapace --store "$STORE" diff +``` + +What to expect: + +- If you created or modified files via `exec`, `diff` reports added/modified/removed paths. + +## 7) Save changes as a snapshot (`commit`) and restore them (`snapshots`, `restore`) + +Create a snapshot from the current overlay: + +```bash +karapace --store "$STORE" commit +``` + +List snapshots: + +```bash +karapace --store "$STORE" snapshots +``` + +Restore from a snapshot: + +```bash +karapace --store "$STORE" restore +``` + +What to expect: + +- `commit` returns a snapshot identifier. +- `snapshots` lists snapshots and includes a `restore_hash` value used with `restore`. +- After `restore`, the overlay directory is replaced with the snapshot content. + +## Next steps + +- Interactive sessions: `karapace enter ` +- Stop a running session from another terminal: `karapace stop ` +- State management: `karapace freeze`, `karapace archive` +- Store maintenance: `karapace verify-store`, `karapace gc`, `karapace destroy` + +For details and flags, see [cli-reference.md](cli-reference.md). diff --git a/docs/imgs/Screenshot_20260225_105438.png b/docs/imgs/Screenshot_20260225_105438.png new file mode 100644 index 0000000..d9b9692 Binary files /dev/null and b/docs/imgs/Screenshot_20260225_105438.png differ diff --git a/docs/imgs/Screenshot_20260225_110134-1.png b/docs/imgs/Screenshot_20260225_110134-1.png new file mode 100644 index 0000000..08c2d19 Binary files /dev/null and b/docs/imgs/Screenshot_20260225_110134-1.png differ diff --git a/docs/imgs/Screenshot_20260225_110134.png b/docs/imgs/Screenshot_20260225_110134.png new file mode 100644 index 0000000..08c2d19 Binary files /dev/null and b/docs/imgs/Screenshot_20260225_110134.png differ diff --git a/docs/imgs/Screenshot_20260225_110215-1.png b/docs/imgs/Screenshot_20260225_110215-1.png new file mode 100644 index 0000000..7b74dab Binary files /dev/null and b/docs/imgs/Screenshot_20260225_110215-1.png differ diff --git a/docs/imgs/Screenshot_20260225_110215.png b/docs/imgs/Screenshot_20260225_110215.png new file mode 100644 index 0000000..7b74dab Binary files /dev/null and b/docs/imgs/Screenshot_20260225_110215.png differ diff --git a/docs/imgs/Screenshot_20260225_110251-1.png b/docs/imgs/Screenshot_20260225_110251-1.png new file mode 100644 index 0000000..e67caa8 Binary files /dev/null and b/docs/imgs/Screenshot_20260225_110251-1.png differ diff --git a/docs/imgs/Screenshot_20260225_110322.png b/docs/imgs/Screenshot_20260225_110322.png new file mode 100644 index 0000000..f804f1f Binary files /dev/null and b/docs/imgs/Screenshot_20260225_110322.png differ