Jon Chery
e9686f4ab0
P04 — README and namespace.md refresh (REQ-095, REQ-096). README.md (REQ-095): - Status line updated (v0.9 complete, v0.10 in progress). - Install --version example updated to v0.9.1 (current). - Added --check dry-run example. - Update-in-place example updated to v0.8.15 -> v0.9.1. - Subcommand table expanded to all 22 commands with Since column and deprecation markers (daemon, cert, status marked deprecated). - Development section complete (verify-reqs, security-scan, test-race, changelog, release). - New Documentation section linking all 7 docs/*.md. - New Examples section linking examples/full-stack/. docs/namespace.md (REQ-096): - Replaced v0.8 flat path table with v0.9 multi-namespace layout (cluster/, _defaults/, per-ns db/jobs/alloc/ns.md, orca_cache.db). - Full path reference table from internal/paths/paths.go. - Namespace root resolution (ORCA_HOME/--system/~/.orca). - orca ns subcommand cross-link to docs/cli.md. - Namespace inheritance (_defaults implicit root, D-159/D-185/D-187). - v0.8 flat layout flagged deprecated with callout box. All README links verified to resolve. make verify-reqs: 98 consistent. ---ci--- project: orca phase: 4 milestone: v0.10 status: execute ---/ci---
Orca
Offline/CLI-first orchestration engine inspired by HashiCorp Nomad, far simpler than Kubernetes.
Status
v0.9: Re-architecture Foundation — COMPLETE | v0.10: Docs & Install Hardening — IN PROGRESS
See .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
- Bug fixes before features — stability is paramount
- NFRs before features — observability and auditability first
Quickstart
Install (1-liner)
# 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
# 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
# Pin a specific version
curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -s -- --version v0.9.1
# 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
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/branch/main/scripts/install.sh | bash
# → "updated orca from v0.8.15 to v0.9.1"
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 |
See docs/cli.md for the full CLI reference with all flags and examples.
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/docker.md | Docker image guide |
| docs/security-scanning.md | Security scanning tools |
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
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)
Architecture
See .ciagent/ARCHITECTURE.md for full architecture details.
License
MIT — see LICENSE.