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.3 KiB

Raw Blame History

End-to-End Testing

Karapace includes end-to-end tests that exercise the real namespace backend with unshare, fuse-overlayfs, and actual container images.

Prerequisites

Linux with user namespace support (CONFIG_USER_NS=y)
fuse-overlayfs installed
curl installed
Network access (images are downloaded from images.linuxcontainers.org)

Install on openSUSE Tumbleweed

sudo zypper install fuse-overlayfs curl

Install on Ubuntu/Debian

sudo apt-get install fuse-overlayfs curl

Install on Fedora

sudo dnf install fuse-overlayfs curl

Running E2E Tests

E2E tests are #[ignore] by default. Run them explicitly:

cargo test --test e2e -- --ignored --test-threads=1

The --test-threads=1 flag is important: E2E tests mount overlays and download images, so parallel execution can cause resource conflicts.

Test Descriptions

Test	What it does
`e2e_build_minimal_namespace`	Build a minimal openSUSE Tumbleweed environment with no packages
`e2e_exec_in_namespace`	Build + exec `echo hello` inside the container
`e2e_destroy_cleans_up`	Build + destroy, verify env_dir is removed
`e2e_rebuild_determinism`	Build + rebuild, verify env_id is identical
`e2e_build_with_packages`	Build with `which` package, verify resolved versions in lock file

CI

The GitHub Actions CI workflow includes an E2E job that runs on ubuntu-latest:

e2e:
  name: E2E Tests
  runs-on: ubuntu-latest
  needs: [test]
  steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - uses: Swatinem/rust-cache@v2
    - name: Install prerequisites
      run: |
        sudo apt-get update -qq
        sudo apt-get install -y -qq fuse-overlayfs curl
        sudo sysctl -w kernel.unprivileged_userns_clone=1 || true        
    - name: Run E2E tests
      run: cargo test --test e2e -- --ignored --test-threads=1

Troubleshooting

"unshare: user namespaces not available" — Enable with sysctl kernel.unprivileged_userns_clone=1
"fuse-overlayfs not found" — Install the fuse-overlayfs package
"failed to download image" — Check network connectivity and DNS
Stale mounts after failed test — Run fusermount3 -u /path/to/merged or reboot

2.3 KiB Raw Blame History