Admin guide
Admin guide
This is the operator-facing reference for running shepard. Everything on this
page cites what is actually in the repository today; the broader
mutating CLI commands and a few sections marked “in design” remain on the
backlog (aidocs/16).
Persona: the operator / SRE / institute IT engineer responsible for keeping a shepard instance healthy. If you are an end-user (researcher / data scientist), start at the user guide. If you are a plugin author, see the plugin docs convention.
Sections
| Page | When to read it |
|---|---|
| System requirements | Before provisioning a host — hardware floor, supported platforms, pinned DB versions, exposed ports. |
| Install | First-time deployment. Compose stack, profiles, deploy paths (bare-metal, paid VPS, managed-services split). |
| Configuration | Tuning a running instance. Env vars, application.properties, runtime :*Config Neo4j singletons, CORS. |
| Upgrade | Moving from upstream shepard 5.2.0 or an earlier fork release to a newer cut. |
| Backup and restore | Per-substrate dump recipes (Neo4j, MongoDB, Postgres/TimescaleDB, PostGIS, S3, HSDS POSIX). |
| Storage substrate | File-storage adapter selection (GridFS, S3 via Garage), migration runbooks, capacity planning. |
| Authentication | OIDC + API-key model, role mapping, instance-admin role, audit trail. |
| Observability | Health endpoints, Prometheus scrape, bundled Grafana dashboard, k6 performance scripts, self-observability TS substrate. |
| Security | CI security gates (SpotBugs, CodeQL, OWASP, Trivy, gitleaks), SBOM, secret rotation. |
Operator runbooks (docs/admin/runbooks/) |
10 numbered runbooks + 3 pre-existing. Quick topics: cube hotpatch (01), orphan payload wipe (02), API key rotation (03), Neo4j restore (04), TimescaleDB restore (05), Garage restore (06), add instance-admin (07), enable plugin (08), permission repair (09), cut a release (10). Plus: migration-chain-integrity, restore-tsdb-container-neo4j-shadow, docker-bind-mount-inode-drift. See runbook index for the decision guide. |
| Database overview (reference) | One-page map of all five substrates — what data lives where, connection commands, which substrate to inspect for a given symptom, schema migration cursors. |
| Troubleshooting databases (task) | Step-by-step fixes for the 7 most common database problems: PgBouncer log spam, CAgg job failure, Garage capacity cap, file download 500s, invisible timeseries containers, migration aborts, Activity node growth. |
Maintainer-facing pages — cutting a release, the GitHub Projects board — live
under docs/ops/; they are not part of the admin guide. See
docs/ops/cut-a-release.md
and docs/ops/github-projects-board-setup.md.
Admin CLI — quick orientation
A read-only shepard-admin CLI ships in L1 Phase 1 — features list,
health, migrations status [containerId]. Build the uber-jar locally:
cd cli
mvn package -DskipTests
export SHEPARD_ADMIN_URL=https://shepard.example.com
export SHEPARD_ADMIN_API_KEY=<instance-admin-roled API key>
java -jar target/shepard-admin-*.jar features list
Full reference, sample output, and exit-code semantics in
Admin CLI (reference).
Phase 2+ (cleanup of soft-deleted entities, RO-Crate import/export, the init
TUI wizard for first-run .env) is queued — see
aidocs/ops/22-admin-cli-draft.md.
Further reading
aidocs/34-upstream-upgrade-path.md— change ledger for admins upgrading from upstream shepard 5.2.0aidocs/44-fork-vs-upstream-feature-matrix.md— per-feature shipped/designed/pending matrix- Bibliography — standards and regulations referenced from this guide (ISO/IEC 42001, EU AI Act, EU Machinery Regulation, Helmholtz FAIR requirements)