docs(bootstrap): clarify three-step Docker first-boot flow
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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user