Jon Chery
4bfc246be4
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---
96 lines
3.3 KiB
Markdown
96 lines
3.3 KiB
Markdown
# 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):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
|
|
1. If `--system` flag is passed → root is `/root/.orca` (errors if
|
|
`ORCA_HOME` is set to a conflicting value).
|
|
2. Else if `ORCA_HOME` is set → root is `$ORCA_HOME`.
|
|
3. 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`).
|
|
|
|
```bash
|
|
export ORCA_DB=/tmp/test.db
|
|
orca daemon # uses /tmp/test.db for the DB, ~/.orca/ for certs
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Install Guide](install.md) — 1-liner install with `install.sh`.
|
|
- [Docker Guide](docker.md) — running orca in a container (uses
|
|
`ORCA_HOME=/var/lib/orca` inside the image). |