Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(docker): serve pending-init details on every HTTP route (#1749)

Zayn Jarvis6bde799bae29
diff --git a/Dockerfile b/Dockerfile
index 6b4fe5c80..69ffa5411 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -118,8 +118,9 @@ WORKDIR /app
COPY --from=py-builder /app/.venv /app/.venv
COPY docker/openviking-console-entrypoint.sh /usr/local/bin/openviking-console-entrypoint
+COPY docker/pending_health_server.py /usr/local/bin/openviking-pending-health
RUN mkdir -p /app/.openviking \
- && chmod +x /usr/local/bin/openviking-console-entrypoint
+ && chmod +x /usr/local/bin/openviking-console-entrypoint /usr/local/bin/openviking-pending-health
ENV HOME="/app" \
PATH="/app/.venv/bin:$PATH" \
OPENVIKING_CONFIG_FILE="/app/.openviking/ov.conf" \
diff --git a/docker/openviking-console-entrypoint.sh b/docker/openviking-console-entrypoint.sh
index 8b06d68bd..20bf92a78 100644
--- a/docker/openviking-console-entrypoint.sh
+++ b/docker/openviking-console-entrypoint.sh
@@ -7,8 +7,18 @@ CONSOLE_PORT="${OPENVIKING_CONSOLE_PORT:-8020}"
CONSOLE_HOST="${OPENVIKING_CONSOLE_HOST:-0.0.0.0}"
WITH_BOT="${OPENVIKING_WITH_BOT:-1}"
CONFIG_FILE="${OPENVIKING_CONFIG_FILE:-/app/.openviking/ov.conf}"
+PENDING_HEALTH_SCRIPT="/usr/local/bin/openviking-pending-health"
SERVER_PID=""
CONSOLE_PID=""
+PENDING_PID=""
+
+stop_pending_health() {
+ if [ -n "${PENDING_PID}" ] && kill -0 "${PENDING_PID}" 2>/dev/null; then
+ kill "${PENDING_PID}" 2>/dev/null || true
+ wait "${PENDING_PID}" 2>/dev/null || true
+ fi
+ PENDING_PID=""
+}
ensure_config() {
if [ -f "${CONFIG_FILE}" ]; then
@@ -28,11 +38,26 @@ To start OpenViking, do one of:
- set OPENVIKING_CONF_CONTENT to the full ov.conf JSON
- docker exec into this container and run: openviking-server init
-The container will sleep until ${CONFIG_FILE} exists.
+While waiting, every HTTP request to this container returns a 503 JSON
+describing the problem and the fix above.
EOF
+ OPENVIKING_CONFIG_FILE="${CONFIG_FILE}" \
+ OPENVIKING_PENDING_PORT="1933" \
+ python "${PENDING_HEALTH_SCRIPT}" &
+ PENDING_PID=$!
+ trap 'stop_pending_health; exit 0' INT TERM
+
while [ ! -f "${CONFIG_FILE}" ]; do
+ if ! kill -0 "${PENDING_PID}" 2>/dev/null; then
+ echo "[openviking-console-entrypoint] pending health server exited unexpectedly" >&2
+ PENDING_PID=""
+ exit 1
+ fi
sleep 5
done
+
+ stop_pending_health
+ trap - INT TERM
echo "[openviking-console-entrypoint] detected ${CONFIG_FILE}, starting OpenViking"
}
diff --git a/docker/pending_health_server.py b/docker/pending_health_server.py
new file mode 100644
index 000000000..9033911c9
--- /dev/null
+++ b/docker/pending_health_server.py
@@ -0,0 +1,101 @@
+"""Pending health server for the OpenViking Docker entrypoint.
+
+While the container is waiting for ``ov.conf`` to appear, the entrypoint
+runs this tiny HTTP server on the same port the real OpenViking server
+will bind. It answers *every* request — `/`, `/health`, anything — with
+the same 503 JSON payload describing what's wrong and how to fix it, so
+operators and agents probing the container can self-discover the issue
+without having to read ``docker logs``.
+
+This is intentionally undocumented in the user guide: it's a 防呆 (poka-yoke
+/ fool-proofing) fallback that only runs when something has already gone
+wrong (no ov.conf and no OPENVIKING_CONF_CONTENT). The happy path never
+sees it, and pointing users at it would imply it's a deployment mode
+worth depending on rather than a safety net. The response body itself is
+self-explanatory when someone does hit it.
+"""
+
+from __future__ import annotations
+
+import http.server
+import json
+import os
+import socketserver
+import sys
+
+_DEFAULT_HOST = "0.0.0.0"
+_DEFAULT_PORT = 1933
+_DEFAULT_CONFIG_FILE = "/app/.openviking/ov.conf"
+
+
+def build_payload(config_file: str) -> dict:
+ """Return the JSON body served on every route."""
+ return {
+ "status": "pending_initialization",
+ "error": "OpenViking config file not found",
+ "config_file": config_file,
+ "fix": [
+ "mount ~/.openviking on the host to /app/.openviking",
+ "set OPENVIKING_CONF_CONTENT to the full ov.conf JSON",
+ "docker exec into this container and run: openviking-server init",
+ ],
+ }
+
+
+def make_handler(config_file: str) -> type[http.server.BaseHTTPRequestHandler]:
+ body = (json.dumps(build_payload(config_file), ensure_ascii=False, indent=2) + "\n").encode(
+ "utf-8"
+ )
+
+ class Handler(http.server.BaseHTTPRequestHandler):
+ def _respond(self) -> None:
+ self.send_response(503)
+ self.send_header("Content-Type", "application/json; charset=utf-8")
+ self.send_header("Content-Length", str(len(body)))
+ self.send_header("Cache-Control", "no-store")
+ self.end_headers()
+ if self.command != "HEAD":
+ self.wfile.write(body)
+
+ do_GET = _respond
+ do_POST = _respond
+ do_PUT = _respond
+ do_PATCH = _respond
+ do_DELETE = _respond
+ do_HEAD = _respond
+ do_OPTIONS = _respond
+
+ def log_message(self, fmt: str, *args) -> None:
+ sys.stdout.write("[openviking-pending-health] " + (fmt % args) + "\n")
+ sys.stdout.flush()
+
+ return Handler
+
+
+class _ReusableServer(socketserver.TCPServer):
+ allow_reuse_address = True
+
+
+def serve(host: str, port: int, config_file: str) -> None:
+ handler = make_handler(config_file)
+ with _ReusableServer((host, port), handler) as httpd:
+ sys.stdout.write(
+ f"[openviking-pending-health] serving on {host}:{port}; waiting for {config_file}\n"
+ )
+ sys.stdout.flush()
+ httpd.serve_forever()
+
+
+def main() -> int:
+ host = os.environ.get("OPENVIKING_PENDING_HOST", _DEFAULT_HOST)
+ port = int(os.environ.get("OPENVIKING_PENDING_PORT", str(_DEFAULT_PORT)))
+ config_file = os.environ.get("OPENVIKING_CONFIG_FILE", _DEFAULT_CONFIG_FILE)
+ try:
+ serve(host, port, config_file)
+ except KeyboardInterrupt:
+ return 0
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())