coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity

docs(P15): README quickstart refresh (REQ-089) — Nomad-inspired framing, honest trade-offs

Browse Source 
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---
This commit is contained in:
Jon Chery
2026-08-07 08:24:34 +00:00
parent c5048822e5
commit cc57ae4c23
1 changed files with 76 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+75 -50
View File
@@ -1,22 +1,28 @@
# Orca # 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 ## 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. See [.ciagent/ROADMAP.md](.ciagent/ROADMAP.md) for the full roadmap.
## Pillars ## Pillars
- **Simplicity** — single binary, minimal dependencies - **Simplicity** — single binary, minimal dependencies, no daemon on the
- **AI-first** — CLI designed for both humans and AI agents critical path
- **Offline-first** — no cloud dependencies - **Offline-first** — no cloud dependencies; the cluster is the OS
- **CLI-first** — primary interface is the command line - **CLI-first** — the command line is the primary interface (humans and
- **Security before features** — NFRs ship before new functionality 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 - **Bug fixes before features** — stability is paramount
- **NFRs before features** — observability and auditability first
## Quickstart ## Quickstart
@@ -24,16 +30,16 @@ See [.ciagent/ROADMAP.md](.ciagent/ROADMAP.md) for the full roadmap.
```bash ```bash
# User-level install (binary at ~/.local/bin/orca, state at ~/.orca) # 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) # 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 # Pin a specific version (latest tag: v0.10.19)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -s -- --version v0.9.1 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 # 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: 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: config, database, and certificates in the namespace dir:
```bash ```bash
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
# → "updated orca from v0.8.15 to v0.9.1" # → "updated orca from v0.8.15 to v0.10.19"
``` ```
## Subcommands ## Subcommands
| Command | Description | Since | | Command | Description |
|---------|-------------|-------| |---------|-------------|
| `orca init` | Initialize local orca state (full bootstrap) | v0.6 | | `orca init` | Initialize local orca state with full bootstrap |
| `orca version` | Print version info | v0.1 | | `orca status` | Show orca daemon status |
| `orca status` | Show orca daemon status (**deprecated** v0.9) | v0.1 | | `orca version` | Print version information |
| `orca job run` | Run a job from a spec file (`.md`/`.yaml`/`.hcl`) | v0.1 | | `orca daemon` | **(deprecated)** Run the orca daemon (HTTP API + health checks) |
| `orca job list` | List all jobs (`--watch` for streaming) | v0.1 | | `orca metrics` | Start metrics endpoint (Prometheus text exposition) |
| `orca job stop` | Stop a running job | v0.1 | | `orca logs` | Aggregate journald logs across nodes (`--all-nodes --since`) |
| `orca job logs` | Show task output for a job | v0.1 | | `orca backup` | Create a signed tar.gz backup of ORCA_HOME |
| `orca node join` | Join a node (`--type proxmox` for SSH-push) | v0.2 | | `orca restore` | Restore ORCA_HOME from a verified signed backup |
| `orca node leave` | Remove a node from the registry | v0.2 | | `orca upgrade` | Upgrade orca to a new version (thin wrapper; R-017 cutover) |
| `orca node list` | List all nodes (`--watch` for streaming) | v0.2 | | `orca node` | Manage orca nodes: `join`, `leave`, `list`, `key-reset`, `drain`, `capacity` |
| `orca node key-reset` | Reset SSH known_hosts entry for a node | v0.8 | | `orca job` | Manage orca jobs: `run`, `list`, `stop`, `logs`, `lint`, `verify`, `migrate`, `restart` |
| `orca node capacity` | Manage node capacity (show/set/list) | v0.2 | | `orca ns` | Manage orca namespaces: `list`, `create`, `delete`, `inspect`, `validate`, `inherit`, `set-constraint` |
| `orca ns list` | List all namespaces | v0.9 | | `orca cert` | **(deprecated)** Manage orca certificates: `ca-init`, `gen`, `show`, `renew`, `fingerprint` |
| `orca ns create` | Create a namespace directory + ns.md | v0.9 | | `orca doctor` | Run self-checks: `cert`, `network`, `db`, `os`, `proxmox`, `no-orca-on-server` |
| `orca ns delete` | Remove an empty namespace | v0.9 | | `orca audit` | View orca audit log (`list`) |
| `orca ns inspect` | Print effective chain, merged env, constraints | v0.9 | | `orca cache` | CLI cache management: `show`, `invalidate`, `invalidate-all` |
| `orca ns validate` | Run cycle + missing-parent + schema checks | v0.9 | | `orca acl` | ACL management: `grant`, `revoke`, `list`, `check` |
| `orca doctor` | Run self-checks (cert/network/db/os/proxmox) | v0.2 | | `orca secrets` | Secrets management: `set`, `get`, `list`, `rotate`, `delete` |
| `orca audit list` | View audit log entries | v0.1 | | `orca drift` | Drift detection: `show`, `watch`, `acknowledge`, `remediate`, `config` |
| `orca daemon` | Run the daemon (**deprecated** v0.9) | v0.1 | | `orca txn` | Transaction management: `apply`, `list`, `show`, `rollback` |
| `orca cert` | Manage certificates (**deprecated** v0.9) | v0.2 | | `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 ## 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/ingress.md](docs/ingress.md) | Ingress guide — Traefik configuration |
| [docs/namespace.md](docs/namespace.md) | Namespace and path layout | | [docs/namespace.md](docs/namespace.md) | Namespace and path layout |
| [docs/install.md](docs/install.md) | Installation guide | | [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 | | [docs/security-scanning.md](docs/security-scanning.md) | Security scanning tools |
## Examples ## Examples
@@ -111,20 +139,17 @@ See [docs/cli.md](docs/cli.md) for the full CLI reference with all flags and exa
## Development ## Development
```bash ```bash
make build # Build binary to ./bin/orca make build # Build binary to ./bin/orca
make test # Run tests make test # Run tests
make test-race # Run tests with race detection go vet ./... # Vet all packages
make lint # Run gofmt + go vet + shellcheck make lint # Run gofmt + go vet + shellcheck
make fmt # Format code make verify-reqs # Assert ROADMAP ↔ REQUIREMENTS consistency
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)
``` ```
## Architecture ## Architecture
See [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) for full architecture details. See [.ciagent/ARCHITECTURE.md](.ciagent/ARCHITECTURE.md) for full
architecture details.
## License ## License