Jon Chery
df3f980fa0
CoreCI's SQLite logging fills the runner's disk during go test -race,
causing the release job to fail when writing the tarball (3-second
failure). The release job ran inside CoreCI's shell-isolated executor
which shares the same disk as CoreCI's SQLite DB.
Fix: move the release logic (build tarball + upload to Gitea) to a
separate Gitea Actions step that runs AFTER coreci run completes.
This step runs in the Gitea Actions runner directly (full env, no
CoreCI disk constraints). The .coreci.yml now only has build→test
jobs. The release is handled by scripts/ci-release.sh called from the
Gitea Actions workflow.
Architecture:
Gitea Actions ci job:
1. Checkout + Set up Go + Install CoreCI
2. coreci run (executes .coreci.yml: build → test)
3. sh scripts/ci-release.sh (build tarball + upload to Gitea API)
---ci---
project: orca
phase: 1
milestone: v0.16
status: execute
---/ci---
Orca
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.12: Security Hardening (Zero-Trust Identity) — COMPLETE | v0.13: Production Hardening Round 2 + UAT Plan — IN PROGRESS | v1.0: UAT-gated (cut separately after v0.13 completion per operator decision)
See .ciagent/ROADMAP.md for the full roadmap.
Pillars
- 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 — SSH-push is the canonical transport (mTLS available for daemon mode); 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
Quickstart
Install (1-liner)
# User-level install (binary at ~/.local/bin/orca, state at ~/.orca)
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/main/scripts/install.sh | sudo bash -s -- --system
# Pin a specific version (latest tag: v0.12.10)
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --version v0.12.10
# Dry-run: check what would be installed without writing
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash -s -- --check
Then initialize local state and verify:
orca init # creates ~/.orca/ (or /root/.orca with --system)
orca version # prints version info
orca --help # show all subcommands
Build from source
make build # Build binary to ./bin/orca
./bin/orca init # Initialize local state
./bin/orca version # Verify
Update in place
Re-running the installer updates the binary while preserving your config, database, and certificates in the namespace dir:
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/main/scripts/install.sh | bash
# → "updated orca from v0.11.28 to v0.12.10"
Subcommands
| Command | Description |
|---|---|
orca init |
Initialize local orca state with full bootstrap |
orca status |
(deprecated v0.1 stub) Show orca daemon status — use orca node list + orca metrics /healthz |
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, nft, audit, modes, oidc, db-retention |
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, rotate-master |
orca drift |
Drift detection: show, watch, acknowledge, remediate, config |
orca txn |
Transaction management: apply, list, show, rollback |
orca nft |
nftables ingress management: show, diff, doctor, country block, rate limit |
orca collector |
Collector/aggregator management: start, stop, status |
orca cluster |
Cluster management: cutover, rotate-lead, compat-check, seal, unseal |
orca auth |
OIDC authentication: login, logout, status, init-idp, register |
orca peer-setup |
Create the orca system user + drift-events dir on a peer (REQ-111) |
See 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 |
| Transport | — | SSH-push is canonical (no daemon needed); mTLS available for daemon mode |
| 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
| Document | Description |
|---|---|
| docs/cli.md | CLI reference — every command, flag, and example |
| docs/jobspec.md | Jobspec reference — markdown frontmatter schema |
| docs/ingress.md | Ingress guide — Traefik configuration |
| docs/namespace.md | Namespace and path layout |
| docs/install.md | Installation guide |
| docs/security-scanning.md | Security scanning tools |
| docs/security-runbook.md | Security runbook — seal/unseal, rotation, incident response |
| docs/webauthn.md | WebAuthn / passkeys registration and login |
| docs/threat-model.md | STRIDE threat model + zero-trust architecture |
| docs/oidc.md | OIDC configuration — Dex quickstart, BYO IdP |
Examples
| Example | Description |
|---|---|
| examples/full-stack/ | Full-stack deployment with ingress (5 services + rendered artifacts) |
Development
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
make verify-docs # Assert docs/cli.md ↔ `orca --help` consistency
Architecture
See .ciagent/ARCHITECTURE.md for full architecture details.
License
MIT — see LICENSE.