docs(bootstrap): clarify three-step Docker first-boot flow
All checks were successful
CVE Scan & Docker Build / security-scan (push) Successful in 51s
CVE Scan & Docker Build / build-and-push (push) Successful in 2m31s

Rework README and docker-compose comments to document the deliberate
chicken-and-egg escape: the `init` sidecar now only runs `migrate` and
`load_library_types`, leaving `setup_neo4j_indexes` as a manual step
after the system embedding model is configured in `/admin/`. This
avoids making `app` unreachable on first boot when no embedding model
row exists yet, while preserving loud failure on dimension mismatch.
This commit is contained in:
2026-05-10 16:15:28 -04:00
parent 19e2aee91c
commit afcbee8819
6 changed files with 102 additions and 155 deletions

View File

@@ -11,8 +11,13 @@ the stderr of a different container.
The probe is deliberately best-effort: it cannot crash the process even if
Neo4j is unreachable, because a transient DB blip on startup should not
take down the whole app. The `init` sidecar is the hard gate; this is the
second line of defence for long-running containers.
take down the whole app. Nothing hard-gates on the vector indexes — the
``init`` sidecar only runs ``migrate`` + ``load_library_types`` (vector
indexes cannot be created before the system embedding model is configured
in the admin, which is a manual step after first boot). This probe is the
only way an operator learns that the manual
``setup_neo4j_indexes`` step was skipped or fell out of sync with the
current system model.
"""
import logging
@@ -149,9 +154,10 @@ def _run_startup_probe():
for name in _EXPECTED_VECTOR_INDEXES:
if name not in present:
logger.error(
"Neo4j vector index '%s' is missing. Run "
"'docker compose run --rm init' (or 'python manage.py "
"setup_neo4j_indexes') to rebuild.",
"Neo4j vector index '%s' is missing. Configure the system "
"embedding model in /admin/llm_manager/llmmodel/, then run "
"'docker compose exec app python manage.py "
"setup_neo4j_indexes' to create it.",
name,
)
continue