# 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).