Contextfulv0.23.0

Docs / Deployment

Cloudflare demo

One Cloudflare Container runs a complete Contextful deployment over this repository’s documentation. A pipeline ingests every Markdown file through the file source each hour. The operator console reads the result. Data shows the workflow, run history, data lineage, row trace and full-text search to anyone; Admin adds the editor and the answer-model choice, and Query answers questions with citations, both behind Cloudflare Access.

Access gates /query and /admin at the edge, and every console path runs through the site Worker’s service binding to the demo Worker, whose one Durable Object wakes a single Container running the console server and the engine:

Flowchart diagram Flowchart, top to bottom. 11 nodes, 13 edges. Browser → Access application [/query, /admin]; → Site Worker [/, /docs, /data] GitHub: GitHub OAuth Cloudflare · deploying account: Access application → GitHub OAuth [login redirect]; → Site Worker [request + Cf-Access-Jwt-Assertion] Cloudflare · deploying account: Site Worker → Site static assets [reads pages]; → Demo Worker [CONSOLE binding: /query, /admin, /data] Cloudflare · deploying account: Site static assets Cloudflare · deploying account: Demo Worker → DemoContainer Durable Object [fetch to instance docs-N, N the generation] Cloudflare · deploying account: DemoContainer Durable Object → Console server :8080 [starts on request; sleeps after 30 min idle] Cloudflare · deploying account / Container · one instance per generation: Console server :8080 → Engine :8081, loopback only [reads and control over loopback HTTP]; → Access application [fetches Access signing keys]; → Workers AI [chat completions with the model token]; → R2 store bucket [reads and writes the answer model, signed S3] Cloudflare · deploying account / Container · one instance per generation: Engine :8081, loopback only → R2 store bucket [pulls and pushes the store] Cloudflare · deploying account: R2 store bucket Cloudflare · deploying account: Workers AI GitHub GitHub OAuth Cloudflare · deployingaccount Container · one instance pergeneration reads and control overloopback HTTP Console server :8080 Engine :8081, loopback only request +Cf-Access-Jwt-Assertion reads pages CONSOLE binding: /query,/admin, /data fetch to instance docs-N, Nthe generation starts on request; sleeps after30 min idle fetches Access signing keys chat completions with themodel token reads and writes the answermodel, signed S3 pulls and pushes the store Access application Site Worker Site static assets Demo Worker DemoContainer DurableObject R2 store bucket Workers AI /query, /admin /, /docs, /data login redirect Browser

The Container sleeps after 30 min idle and its disk does not survive. Set CONTEXTFUL_SYNC_ENDPOINT and CONTEXTFUL_SYNC_BUCKET to keep the store in an S3-compatible bucket: each boot pulls the store, rebuilds its run rows, ingests what changed and pushes, so run history and applied documents survive. A bucket needs the secrets CONTEXTFUL_SYNC_ACCESS_KEY_ID, CONTEXTFUL_SYNC_SECRET_ACCESS_KEY, CONTEXTFUL_DEMO_ISSUER_SEED (a base64 issuer seed), CONTEXTFUL_DEMO_ISSUER_PUBLIC_KEY and CONTEXTFUL_DEMO_PEPPER, which stay fixed across boots. Without a bucket, each boot starts from the image with its own issuer key.

The engine admits a network bearer living at most 3600 s, so image/renew.mjs mints the console’s two credentials again every 50 min.

Deploying

The deployment needs an identity gate and a site Worker. One Cloudflare Access application covers /query and /admin with a hostname-scoped cookie, so one sign-in reaches both pages; set both console audience settings to its audience. The site Worker forwards /admin*, /query* and /data* to the demo Worker over a service binding.

cargo zigbuild --release --locked -p contextful-cli --bin contextful \
  --no-default-features --features contextful-full --target x86_64-unknown-linux-musl
npm install
npm run prepare-image -- <path to the musl binary>
cp wrangler.example.jsonc wrangler.deploy.jsonc   # untracked; fill in the placeholders
npm run deploy

Set CONTEXTFUL_CONSOLE_PUBLIC_DATA to 1 to serve /data without a login: the workflow, run history, lineage, row trace and full-text search Admin shows, read-only. Admin and Query stay behind the identity gate, so route /data to the console outside it.

A deploy leaves a running Container on its old image and settings. Raise CONTEXTFUL_DEMO_GENERATION to start a fresh one; the old one stops after 30 min idle.

Query writes answers when CONTEXTFUL_MODEL_ENDPOINT names an OpenAI-compatible endpoint and CONTEXTFUL_MODEL_CHOICES lists the models an editor may pick in Admin’s Query answers section; the secret CONTEXTFUL_MODEL_TOKEN carries the endpoint’s key. With a bucket the choice, including off, persists at console/answers.json. With answers off Query lists the closest passages.

wrangler deploy needs a running Docker daemon to build the image, and a rollout can leave a running instance on its old image, so after wrangler deploy reports the rollout complete, raise the generation. Full-text search and Data need no model.