# Operator guide

## Run locally

```bash
make install
make run
```

The API defaults to `127.0.0.1:8010` and `./sbom-nexus.db`. Set
`SBOM_NEXUS_DATABASE_PATH` to an explicit durable location for non-development
use.

## Register and ingest a repository

```bash
curl -X PUT http://127.0.0.1:8010/repositories/example \
  -H 'Content-Type: application/json' \
  -d '{"checkout_path":"/srv/repos/example","active":true}'

curl -X POST http://127.0.0.1:8010/sbom/example/ingest
```

The ingest response is terminal: `ingested`, or `skipped` with one of
`no-checkout`, `no-manifest`, or `ingest-error`. A skip advances queue fairness
but does not advance `last_success_at`.

## Inspect catch-up

```bash
curl -s 'http://127.0.0.1:8010/sbom/catch-up?limit=3' | python3 -m json.tool
```

The default stale threshold is 30 days. Override it globally with
`SBOM_NEXUS_STALE_DAYS` or per query with `stale_days` during controlled
operation.

## Import State Hub history

Run a read-only preview first:

```bash
uv run python scripts/import_state_hub.py --dry-run
```

Then run against a backed-up Nexus database:

```bash
uv run python scripts/import_state_hub.py \
  --source-url http://127.0.0.1:8000 \
  --target-url http://127.0.0.1:8010
```

Imports are idempotent on the State Hub snapshot UUID. Before cutover, compare
the source/target repository, snapshot, and entry counts described in the
extraction review. The current script reports counts but is not yet the complete
production reconciliation gate.

## Current production limitations

- The extraction store is SQLite and intended for local/single-node operation.
- Authentication and authorization are not yet integrated.
- Structured operational metrics, PostgreSQL migrations, backup/restore proof,
  and retention policy are required before authority cutover.
- State Hub and Repo Manager callers have not yet been retargeted.