From cc57ae4c23157560512601d108b15cb3b875a49b Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Fri, 7 Aug 2026 08:24:34 +0000 Subject: [PATCH] =?UTF-8?q?docs(P15):=20README=20quickstart=20refresh=20(R?= =?UTF-8?q?EQ-089)=20=E2=80=94=20Nomad-inspired=20framing,=20honest=20trad?= =?UTF-8?q?e-offs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subcommand table expanded to all 22 v0.11 commands (incl. drift, nft, migrate, rotate-lead, upgrade, logs --all-nodes, doctor no-orca-on-server, txn, collector, cluster). Honest trade-offs table (K8s wins: ecosystem/ talent/scale; Orca wins: no-daemon/OS-native/mTLS/offline/WASM/Proxmox). Install example pinned to latest tag. Documentation + Examples sections. ---ci--- project: orca phase: 15 milestone: v0.11 status: execute ---/ci--- --- README.md | 127 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 76 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 87299b5..e36c77a 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,28 @@ # Orca -Offline/CLI-first orchestration engine inspired by HashiCorp Nomad, far simpler than Kubernetes. +A minimalist, offline-first, CLI-first orchestration engine inspired by +HashiCorp Nomad. Proxmox is one supported node type — not the project's +identity. ## Status -**v0.9: Re-architecture Foundation — COMPLETE** | **v0.10: Docs & Install Hardening — IN PROGRESS** +**v0.11: Production Hardening — IN PROGRESS** | **v1.0: UAT-gated** (cut +separately after v0.11 completion per operator decision) See [.ciagent/ROADMAP.md](.ciagent/ROADMAP.md) for the full roadmap. ## Pillars -- **Simplicity** — single binary, minimal dependencies -- **AI-first** — CLI designed for both humans and AI agents -- **Offline-first** — no cloud dependencies -- **CLI-first** — primary interface is the command line -- **Security before features** — NFRs ship before new functionality +- **Simplicity** — single binary, minimal dependencies, no daemon on the + critical path +- **Offline-first** — no cloud dependencies; the cluster is the OS +- **CLI-first** — the command line is the primary interface (humans and + AI agents) +- **Security before features** — mTLS by default; NFRs ship before new + functionality +- **WASM-first** — workloads target OS primitives (systemd units, + journald), not a container runtime shim - **Bug fixes before features** — stability is paramount -- **NFRs before features** — observability and auditability first ## Quickstart @@ -24,16 +30,16 @@ See [.ciagent/ROADMAP.md](.ciagent/ROADMAP.md) for the full roadmap. ```bash # User-level install (binary at ~/.local/bin/orca, state at ~/.orca) -curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash +curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash # System-level install (binary at /usr/local/bin/orca, state at /root/.orca) -curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | sudo bash -s -- --system +curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | sudo bash -s -- --system -# Pin a specific version -curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -s -- --version v0.9.1 +# Pin a specific version (latest tag: v0.10.19) +curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --version v0.10.19 # Dry-run: check what would be installed without writing -curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -s -- --check +curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --check ``` Then initialize local state and verify: @@ -58,37 +64,60 @@ Re-running the installer updates the binary while preserving your config, database, and certificates in the namespace dir: ```bash -curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -# → "updated orca from v0.8.15 to v0.9.1" +curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash +# → "updated orca from v0.8.15 to v0.10.19" ``` ## Subcommands -| Command | Description | Since | -|---------|-------------|-------| -| `orca init` | Initialize local orca state (full bootstrap) | v0.6 | -| `orca version` | Print version info | v0.1 | -| `orca status` | Show orca daemon status (**deprecated** v0.9) | v0.1 | -| `orca job run` | Run a job from a spec file (`.md`/`.yaml`/`.hcl`) | v0.1 | -| `orca job list` | List all jobs (`--watch` for streaming) | v0.1 | -| `orca job stop` | Stop a running job | v0.1 | -| `orca job logs` | Show task output for a job | v0.1 | -| `orca node join` | Join a node (`--type proxmox` for SSH-push) | v0.2 | -| `orca node leave` | Remove a node from the registry | v0.2 | -| `orca node list` | List all nodes (`--watch` for streaming) | v0.2 | -| `orca node key-reset` | Reset SSH known_hosts entry for a node | v0.8 | -| `orca node capacity` | Manage node capacity (show/set/list) | v0.2 | -| `orca ns list` | List all namespaces | v0.9 | -| `orca ns create` | Create a namespace directory + ns.md | v0.9 | -| `orca ns delete` | Remove an empty namespace | v0.9 | -| `orca ns inspect` | Print effective chain, merged env, constraints | v0.9 | -| `orca ns validate` | Run cycle + missing-parent + schema checks | v0.9 | -| `orca doctor` | Run self-checks (cert/network/db/os/proxmox) | v0.2 | -| `orca audit list` | View audit log entries | v0.1 | -| `orca daemon` | Run the daemon (**deprecated** v0.9) | v0.1 | -| `orca cert` | Manage certificates (**deprecated** v0.9) | v0.2 | +| Command | Description | +|---------|-------------| +| `orca init` | Initialize local orca state with full bootstrap | +| `orca status` | Show orca daemon status | +| `orca version` | Print version information | +| `orca daemon` | **(deprecated)** Run the orca daemon (HTTP API + health checks) | +| `orca metrics` | Start metrics endpoint (Prometheus text exposition) | +| `orca logs` | Aggregate journald logs across nodes (`--all-nodes --since`) | +| `orca backup` | Create a signed tar.gz backup of ORCA_HOME | +| `orca restore` | Restore ORCA_HOME from a verified signed backup | +| `orca upgrade` | Upgrade orca to a new version (thin wrapper; R-017 cutover) | +| `orca node` | Manage orca nodes: `join`, `leave`, `list`, `key-reset`, `drain`, `capacity` | +| `orca job` | Manage orca jobs: `run`, `list`, `stop`, `logs`, `lint`, `verify`, `migrate`, `restart` | +| `orca ns` | Manage orca namespaces: `list`, `create`, `delete`, `inspect`, `validate`, `inherit`, `set-constraint` | +| `orca cert` | **(deprecated)** Manage orca certificates: `ca-init`, `gen`, `show`, `renew`, `fingerprint` | +| `orca doctor` | Run self-checks: `cert`, `network`, `db`, `os`, `proxmox`, `no-orca-on-server` | +| `orca audit` | View orca audit log (`list`) | +| `orca cache` | CLI cache management: `show`, `invalidate`, `invalidate-all` | +| `orca acl` | ACL management: `grant`, `revoke`, `list`, `check` | +| `orca secrets` | Secrets management: `set`, `get`, `list`, `rotate`, `delete` | +| `orca drift` | Drift detection: `show`, `watch`, `acknowledge`, `remediate`, `config` | +| `orca txn` | Transaction management: `apply`, `list`, `show`, `rollback` | +| `orca collector` | Collector/aggregator management: `start`, `stop`, `status` | +| `orca cluster` | Cluster management: `cutover`, `rotate-lead`, `compat-check` | -See [docs/cli.md](docs/cli.md) for the full CLI reference with all flags and examples. +See [docs/cli.md](docs/cli.md) for the full CLI reference with all flags +and examples. + +## Honest trade-offs + +Orca is not a Kubernetes replacement for every workload. This table is +the honest comparison — K8s wins in several dimensions, and that is +acknowledged rather than papered over. + +| Dimension | Kubernetes wins | Orca wins | +|-----------|-----------------|-----------| +| Ecosystem | Mature CNCF ecosystem; vast operator, controller, plugin surface | — | +| Talent pool | Large pool of K8s-experienced engineers | — | +| Multi-cloud | Portable across all major clouds; control plane is cloud-agnostic | — | +| Stateful operators | Rich operator pattern (CRD + controller) for stateful workloads | — | +| Service mesh | First-class service mesh (Istio, Linkerd) | — | +| Auto-scaling | Cluster autoscaler, HPA/VPA, deep integrations | — | +| Daemon footprint | — | No daemon on the critical path; the cluster is the OS | +| OS-native | — | Workloads are systemd units + journald; no container runtime shim | +| mTLS | — | mTLS by default; no opt-in required | +| Offline-first | — | No cloud dependencies; fully air-gapped operation | +| WASM-first | — | Workloads target OS primitives, not a container runtime | +| Proxmox | — | First-class Proxmox node type (`--type proxmox`) via SSH-push | ## Documentation @@ -99,7 +128,6 @@ See [docs/cli.md](docs/cli.md) for the full CLI reference with all flags and exa | [docs/ingress.md](docs/ingress.md) | Ingress guide — Traefik configuration | | [docs/namespace.md](docs/namespace.md) | Namespace and path layout | | [docs/install.md](docs/install.md) | Installation guide | -| [docs/docker.md](docs/docker.md) | Docker image guide | | [docs/security-scanning.md](docs/security-scanning.md) | Security scanning tools | ## Examples @@ -111,21 +139,18 @@ See [docs/cli.md](docs/cli.md) for the full CLI reference with all flags and exa ## Development ```bash -make build # Build binary to ./bin/orca -make test # Run tests -make test-race # Run tests with race detection -make lint # Run gofmt + go vet + shellcheck -make fmt # Format code -make security-scan # Run gosec + govulncheck + gitleaks -make verify-reqs # Assert ROADMAP ↔ REQUIREMENTS consistency -make changelog # Generate CHANGELOG.md from ---ci--- blocks -make release # Build + create Gitea release (VERSION required) +make build # Build binary to ./bin/orca +make test # Run tests +go vet ./... # Vet all packages +make lint # Run gofmt + go vet + shellcheck +make verify-reqs # Assert ROADMAP ↔ REQUIREMENTS consistency ``` ## Architecture -See [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) for full architecture details. +See [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) for full +architecture details. ## License -MIT — see [LICENSE](LICENSE). \ No newline at end of file +MIT — see [LICENSE](LICENSE).