docs: significantly expand deployment runbook for beginners

Author: Thomas Tupper

README.md

@@ -1,36 +1,82 @@
 # foxmemory-deploy
 
-Deployment pack for FoxMemory.
+Deployment recipes for the FoxMemory stack.
 
-## Modes
-1. `compose.one.yml` — one-node (infer + store-with-embedded-qdrant)
-2. `compose.split.yml` — split topology (infer and store on different infrastructure)
-3. `compose.external.yml` — store only; inference via external OpenAI-compatible API
+If you’re new to infra: this repo is the "how to run it" layer. It does not contain core API code; it contains Docker Compose topologies and runbooks.
+
+## What this repo is for
+
+- Start FoxMemory services with sane defaults
+- Choose a topology based on your environment
+- Provide smoke tests and operations runbooks
+
+## Topologies
+
+1. **`compose.one.yml`** — one-node stack (`infer` + `store`)
+2. **`compose.split.yml`** — split deployment across environments
+3. **`compose.external.yml`** — only `store`; inference from an external OpenAI-compatible provider
+
+---
 
 ## Quick start (one-node)
+
 ```bash
 cp .env.example .env
 docker compose -f compose.one.yml up -d
 ```
 
-## Verify
+Health checks:
+
 ```bash
 curl -s http://localhost:8081/health
 curl -s http://localhost:8082/health
 ```
 
-## Smoke test
+Stop:
+
 ```bash
-curl -s -X POST http://localhost:8082/v1/memories \
-  -H 'content-type: application/json' \
-  -d '{"user_id":"demo","messages":[{"role":"user","content":"I like sci-fi movies"}]}'
+docker compose -f compose.one.yml down -v
+```
+
+---
+
+## Smoke tests
 
-curl -s -X POST http://localhost:8082/v1/memories/search \
-  -H 'content-type: application/json' \
-  -d '{"user_id":"demo","query":"movie preference","top_k":5}'
+### One-node smoke
+
+```bash
+bash scripts/smoke-one.sh
 ```
 
-## Design contract
-- `foxmemory-store` requires no external container other than optional `foxmemory-infer`.
-- Inference integration uses OpenAI-compatible API shape.
-- Embedded Qdrant is included in store container for two-container deployments.
+### External-provider smoke
+
+```bash
+cp .env.example .env
+# set OPENAI_BASE_URL and OPENAI_API_KEY for your provider
+bash scripts/smoke-external.sh
+```
+
+---
+
+## Env file basics
+
+The `.env` file configures image tags, model names, and provider keys.
+
+Most important fields:
+
+- `FOXMEMORY_INFER_IMAGE`
+- `FOXMEMORY_STORE_IMAGE`
+- `OPENAI_BASE_URL`
+- `OPENAI_API_KEY`
+- `MEM0_LLM_MODEL`
+- `MEM0_EMBED_MODEL`
+
+---
+
+## Docs to read next
+
+- `docs/RUNBOOK.md` — step-by-step operations guide
+
+## License
+
+MIT (see `LICENSE` in service repos)

docs/RUNBOOK.md

@@ -1,29 +1,102 @@
-# Runbook
+# FoxMemory Deploy Runbook (n00b-friendly)
+
+This runbook assumes you are new to containers and just want a reliable checklist.
+
+## 0) Prerequisites
+
+- Docker Desktop (or Docker Engine + Compose plugin)
+- Ports available: `8081` and `8082`
+- Internet access if pulling images from Docker Hub
+
+## 1) Prepare env
 
-## Start one-node mode
 ```bash
 cp .env.example .env
+```
+
+Open `.env` and verify values:
+- image names point to valid images
+- `OPENAI_BASE_URL` points where you think it does
+- model names exist in your inference backend
+
+## 2) Start one-node stack
+
+```bash
 docker compose -f compose.one.yml up -d
 ```
 
-## Health checks
+## 3) Validate service health
+
 ```bash
 curl -s http://localhost:8081/health
 curl -s http://localhost:8082/health
 ```
 
-## Basic memory write/search
+Expected: both return JSON with `ok: true`.
+
+## 4) Validate memory path
+
+Write:
+
 ```bash
 curl -s -X POST http://localhost:8082/v1/memories \
   -H 'content-type: application/json' \
-  -d '{"user_id":"demo","messages":[{"role":"user","content":"remember I prefer concise responses"}]}'
+  -d '{"user_id":"demo","messages":[{"role":"user","content":"remember I prefer concise replies"}]}'
+```
 
+Search:
+
+```bash
 curl -s -X POST http://localhost:8082/v1/memories/search \
   -H 'content-type: application/json' \
   -d '{"user_id":"demo","query":"response preference","top_k":5}'
 ```
 
-## Stop
+## 5) Tear down
+
 ```bash
-docker compose -f compose.one.yml down
+docker compose -f compose.one.yml down -v
+rm -f .env
 ```
+
+---
+
+## Common failures and fixes
+
+### A) `service has neither an image nor a build context`
+
+Cause: env vars for image names are missing.
+
+Fix: ensure `.env` exists and includes `FOXMEMORY_INFER_IMAGE` + `FOXMEMORY_STORE_IMAGE`.
+
+### B) `401 Incorrect API key` during memory write
+
+Cause: store is calling a provider that requires a real key, or provider base URL not correctly applied.
+
+Fix:
+- verify `OPENAI_BASE_URL`
+- verify `OPENAI_API_KEY`
+- verify provider accepts OpenAI-compatible API shape
+
+### C) Qdrant connection refused (`127.0.0.1:6333`)
+
+Cause: embedded Qdrant not started or not reachable from store process.
+
+Fix:
+- check store logs
+- verify image version and entrypoint behavior
+- verify qdrant-related env vars
+
+Logs:
+
+```bash
+docker compose -f compose.one.yml logs --tail=200 store infer
+```
+
+---
+
+## Operational tips
+
+- Pin images to explicit tags in production (avoid `latest`)
+- Keep a known-good `.env` template per environment
+- Add CI smoke tests for every image publish