Files

T

Jon Chery 4bfc246be4 feat(P01): unified namespace root via ORCA_HOME + --system flag

REQ-041: ORCA_HOME is now the single namespace root for all components
  (db, certs, init, daemon). store.Open("") and init command both
  route through certpaths.Dir()/DBPath() instead of hardcoding ~/.orca.
  Backward compatible: empty ORCA_HOME -> ~/.orca.

REQ-042: --system persistent flag on rootCmd sets ORCA_HOME=/root/.orca
  via PersistentPreRunE. Errors on conflict with pre-set ORCA_HOME.

Tests: 7 new tests in namespace_test.go (default, ORCA_HOME override,
  --system sets root, conflict detection, init --json, flag registered).
  Full suite passes (no regressions).

Docs: docs/namespace.md covers default, ORCA_HOME, --system, ORCA_DB,
  resolution order, and path layout tables.

---ci---
project: orca
phase: 1
milestone: v0.5
status: verify
---/ci---

2026-08-03 18:05:01 +00:00

3.3 KiB

Raw Blame History

Namespace and Paths

Orca stores all on-disk state (SQLite database, CA certs, server certs, config) under a single namespace root directory. This document describes how that root is resolved and how to override it.

Default: User-Level (`~/.orca`)

By default, the namespace root is ~/.orca (i.e., $HOME/.orca). All orca state lives under this directory:

Path	Contents
`~/.orca/orca.db`	SQLite database (jobs, nodes, tasks, audit log, capacity)
`~/.orca/ca.crt`	CA certificate (PEM, mode 0644)
`~/.orca/ca.key`	CA private key (PEM, mode 0600)
`~/.orca/server.crt`	Server certificate (PEM, mode 0644)
`~/.orca/server.key`	Server private key (PEM, mode 0600)

Override: `ORCA_HOME` Environment Variable (REQ-041)

Set the ORCA_HOME environment variable to change the namespace root for all orca components (database, certs, init, daemon):

export ORCA_HOME=/var/lib/orca
orca init          # creates /var/lib/orca/
orca daemon        # reads /var/lib/orca/orca.db
orca cert ca-init  # writes CA to /var/lib/orca/

This is the single source of truth for the namespace root. Every component that reads or writes on-disk state resolves the root via ORCA_HOME (falling back to ~/.orca when unset).

Use cases

Testing: point ORCA_HOME at a temp directory.
Multi-instance: run multiple orca daemons on the same host with different ORCA_HOME values.
Custom layout: store state on a mounted volume (ORCA_HOME=/mnt/orca-data).

System-Level: `--system` Flag (REQ-042)

The --system persistent flag selects the system-level namespace root /root/.orca. This is intended for root-owned system deployments (where orca runs as a system service under root):

sudo orca --system init          # creates /root/.orca/
sudo orca --system daemon        # reads /root/.orca/orca.db
sudo orca --system cert ca-init  # writes CA to /root/.orca/

The --system flag is equivalent to setting ORCA_HOME=/root/.orca, but it is a CLI convenience that does not require exporting an env var. If ORCA_HOME is already set to a different value, --system returns an error (to avoid silent namespace mismatches).

Path layout

System-level uses the same directory shape as user-level, just under /root/.orca instead of ~/.orca:

Path	Contents
`/root/.orca/orca.db`	SQLite database
`/root/.orca/ca.crt`	CA certificate
`/root/.orca/ca.key`	CA private key
`/root/.orca/server.crt`	Server certificate
`/root/.orca/server.key`	Server private key

Resolution Order

If --system flag is passed → root is /root/.orca (errors if ORCA_HOME is set to a conflicting value).
Else if ORCA_HOME is set → root is $ORCA_HOME.
Else → root is ~/.orca ($HOME/.orca).

`ORCA_DB` Override

For finer-grained control, ORCA_DB overrides only the database path (not the cert paths). This is primarily a testing affordance. When ORCA_DB is set, certs still resolve under ORCA_HOME (or ~/.orca).

export ORCA_DB=/tmp/test.db
orca daemon   # uses /tmp/test.db for the DB, ~/.orca/ for certs

3.3 KiB Raw Blame History

Namespace and Paths

Default: User-Level (~/.orca)

Override: ORCA_HOME Environment Variable (REQ-041)