DEPLOYMENT_GUIDE.md

Deployment and loading-speed guide

If using the standalone HF zip, its root already contains the HF application; omit the cd hf step below. Frontend/assets are in the complete package.

1. Keep a rollback copy

Export the current HF Space files, keep the current LibGuides source block, and back up any runtime configuration/feedback/metrics you need. Never place real secrets in the replacement archive, LibGuides JavaScript, or a public repository.

2. Upload the HF source

Copy the contents of hf/ into the root of the existing Docker Space. Preserve the Space's settings and secrets. app.py, Dockerfile, requirements.txt, README.md, and src/ must be at the repository root, not nested under an extra hf/ folder.

Use the complete supplied knowledge directory. Duplicate (1).txt variants have been merged into their canonical files; remove those old duplicate files from the destination so they are not indexed again. Empty placeholder files and git/test caches are not deployment inputs.

The container runs as UID 1000 on port 7860. Dockerfile uses the liveness endpoint for its health check. Initial semantic-index creation happens in the background; local keyword retrieval becomes available first.

3. Check configuration

Secret/variable	Required use
ENVIRONMENT	production for the deployed Space.
ORIGIN_TOKEN	Must match your Worker's HF_ORIGIN_TOKEN. Protected origin routes reject missing/wrong tokens.
OPENAI_API_KEY	Needed for the configured GPT answers, classification and semantic embeddings. Without it, some deterministic library responses/local retrieval can still work, but the model service is degraded.
ADMIN_PASSWORD	Required to log in to the HF admin page.
CLOUDFLARE_WORKER_URL	Existing gateway URL; keep it consistent with frontend API_URL.
CLOUDFLARE_ADMIN_TOKEN	Must match Worker ADMIN_TOKEN; used for the existing admin/analytics token contract.
LIBCAL_CLIENT_ID, LIBCAL_CLIENT_SECRET	Required for live library hours.
LIBCAL_EVENTS_CLIENT_ID, LIBCAL_EVENTS_CLIENT_SECRET	Optional separate events credentials; otherwise main LibCal credentials are reused.
PRIMO_API_KEY	Enables your existing direct PRIMO API integration where configured.
ANTHROPIC_API_KEY	Optional; needed if you enable Claude.
OPENALEX_API_KEY	Optional server-side key for the existing scholarly fallback. Basic anonymous usage remains supported.
CONTACT_EMAIL	Institutional contact for scholarly API requests.
RUNTIME_DIR	A writable runtime directory; use /data/libbee_runtime only if that path is your configured durable mount.
ALLOWED_CORS_ORIGINS	Explicit browser origins if directly calling permitted HF endpoints from a separate site; the intended student chat path remains through the Worker.

See hf/.env.example for supported examples and request limits. It contains placeholders, not credentials. Do not upload a filled .env to a public repository.

Creating /data in a Docker build does not make it persistent. Verify your Space's actual mounted durable storage and its UID-1000 permissions. On ephemeral disk, restarts lose cache/runtime data. Current HF Docker documentation describes runtime persistence options and permissions: Docker Spaces.

4. Check the existing Worker contract

The Worker code was not supplied. Confirm these against it before live rollout:

• Browser requests use /agent, /feedback, and /config at API_URL; JSON chat/feedback requests include the existing X-LibBee-Session header.
• The Worker adds X-LibBee-Origin-Token only on its server-to-HF calls. The permanent origin and admin secrets must never appear in student JavaScript.
• Forward the HF agent JSON fields expected by the frontend: answer, request_id, intent/tools, source links, search context, and follow-up suggestions.
• Preserve useful HTTP status codes for malformed requests, busy/maintenance states and provider failures. Do not cache chat or feedback responses.
• The Worker owns persistent analytics and session enforcement. Confirm feedback ownership, analytics writes, rate limits and D1 schema using its actual source.
• Allow the actual KU LibGuides origin in Worker CORS, including JSON requests and the session header.
• Verify that the current Worker accepts the HF admin's existing short-lived signed analytics:read token format. The permanent secret remains server-side.
• If /config reaches a sleeping HF Space, the revised front end still renders and permits typing without waiting for configuration to return.

5. Replace the LibGuides block

On a staging page, replace the old source block with all of frontend/libbee-libguides.html. The block contains its own CSS, HTML, JavaScript and small embedded images; no image hosting setup is needed. Keep the normal LibGuides page wrapper.

The default API_URL remains the gateway found in your supplied files. Change this one configuration value only if you are moving to a different gateway. Add the staging/production page origins to the Worker's CORS allowlist as needed.

Do not paste both the old and new blocks into one page. Duplicate IDs or event handlers can submit a question twice. The revised layout stays within the chatbot container and does not force the whole LibGuides page to become full width.

6. Validate before switching users

In an environment with package/network access:

cd hf
python -m pip install -r requirements-dev.txt
python -m pip check
python -m compileall -q app.py src tests
pytest -q

Run a current dependency-vulnerability scan against the resolved environment, then lock and retest compatible patched packages. This review retained the supplied dependency pins to avoid an untested framework migration; it does not certify that those old pins or their transitive resolution are current or vulnerability-free.

Start the container/Space and check:

Check	Expected result
/health/live	HTTP 200 once the application is listening; version 4.1.1.
/config while embeddings are initializing	Responds without waiting for semantic index construction.
/health/ready	HTTP 503 while retrieval is unavailable or origin configuration is invalid; reports readiness/degraded state honestly once local retrieval is available.
Direct /agent request without the origin token	Rejected in production.
Gateway chat	Greeting, opening hours, staff, database help, article search, books, PubMed, and follow-ups work using real credentials.
Cancel/Clear/Home during a slow answer	No late answer appears in a new/cleared conversation.
Unavailable gateway/slow request	Visible progress/error/retry controls; no silent frozen composer.
Feedback	Save one up/down vote through the Worker and confirm the expected analytics ownership.
Admin login/logout	Logged-out session stays invalid, including after reloading persisted sessions.
Maintenance	Normal submission, suggested questions and follow-ups respect maintenance.
Real browser	Desktop + narrow mobile; keyboard focus; sources/copy/expand controls; no console errors or page-wide style changes.

Admin's write canary is now an explicit POST action. Read-only health GETs do not run paid/write diagnostics. Verify the actual Worker canary endpoint separately if used.

7. Understand what still controls loading speed

The revised front end is smaller and does not wait for configuration before displaying the interface. HF no longer waits for remote embeddings to finish before serving basic endpoints. Stable content hashes let the semantic cache survive ordinary rebuilds when stored on a durable mount. The new cache schema forces one rebuild of older cache files.

A sleeping HF Space still needs to wake. HF documents that CPU Basic sleeps after inactivity and upgraded hardware can remain running. Check the current Space hardware/sleep settings if the first visit after a long idle period remains slow; changing hardware was not performed during this review. HF sleep settings.

Measure the warm and idle-first-visit cases separately in browser Network tools: document download, /config, first /agent request, and later /agent requests. No production latency reduction in seconds is claimed by this package because deployed timing data was not available.

Rollback

Restore the previous HF source and the previous LibGuides source block together, retaining the matching Worker tokens and endpoint URL. Restore runtime-data backups if needed. New signed caches can be discarded and rebuilt; never accept an unsigned pickle/index file to make rollback appear faster.