athena-oracle/docs/Deployment-Plan.md

Deployment Plan — Athena MVP

Deployment reality (updated 2026-07-12): This plan originally required Docker. The deployed system does not use containers — it runs as bare Python scripts under the vpsadmin standard user, driven by Hermes cron (oracle-pipeline.sh at 13:00 UTC). Ollama is also not deployed; summarization is deferred (graceful degradation is live). The Docker steps below are retained as the future containerization target, not the current procedure.

Prerequisites

• Python 3 + pip on the target host (no Docker required for current deployment)
• Network access to the 6 source APIs/feeds (arxiv, github, huggingface, hackernews, reddit, rss_feeds)
• GITHUB_TOKEN available as an environment variable (optional, but raises the GitHub rate limit from 60/hr to 5000/hr)
• HUGGINGFACE_TOKEN available as an environment variable
• (Future/optional) A local Ollama instance running llama3.2:1b, or an alternate reachable inference backend if swapping — per the model-agnostic summarize(text) -> (summary, model) contract
• Hermes cron infrastructure available and able to invoke oracle-pipeline.sh

Setup

1. Clone main (not a milestone branch) onto the target host
2. pip install -r requirements.txt if present; otherwise confirm stdlib + requests are available
3. Run schema.sql against a fresh oracle.db — this file is git-ignored and created locally, never committed
4. Create /home/vpsadmin/oracle/.env with GITHUB_TOKEN and HUGGINGFACE_TOKEN, then chmod 600 .env — never hardcode these
5. (Future container target) Build and run inside Docker with the 150MB memory cap and non-root user enforced, per the PRD platform requirements
6. Manual smoke test: run python3 pipeline.py once and confirm ingest → store → score completes without errors before handing off to cron

Current state: steps 1–4 + 6 are the live procedure. Oracle-pipeline.sh sources .env and runs the bare pipeline; no Docker involved.

Cron / Scheduling

1. Confirm oracle-pipeline.sh is the entry point Hermes cron calls
2. Schedule for 13:00 UTC daily
3. Add a lock file or PID check so overlapping runs can't happen if a prior run is still in progress
4. Confirm the cron environment actually carries the exported tokens — cron environments are frequently minimal and won't inherit an interactive shell's exports

Hermes Integration

1. Confirm the wrapper script's exit codes are meaningful (0 = success, non-zero = failure) so Hermes can act on them
2. Define where Hermes should look for pipeline output/logs
3. Decide on a failure-notification path (Hermes alert, log flag, etc.) — not yet specified, needs a decision

Monitoring

1. Aggregate logs from each pipeline stage (ingest, store, summarize, score)
2. Track theme-scan new-arrival counts per cycle per theme — this is the core signal the falsification logic depends on, so it deserves visibility beyond raw logs
3. Add a heartbeat/dead-man's-switch alert if a scheduled run doesn't fire, rather than relying on someone noticing missing data days later
4. Watch memory usage against the 150MB cap under real production load, not just dev conditions

Rollback

1. Back up oracle.db before any schema change — it's git-ignored and not recoverable from the repo itself
2. If a bad deploy breaks the pipeline, revert to the last known-good commit on main and redeploy the bare scripts
3. (Future container target) revert to last known-good commit on main and redeploy the Docker image
4. Check falsification state (new-arrivals counters) after any rollback — rolling back mid-window could distort the 7-day dead-thesis calculation if not handled carefully

---

Draft prepared by Claude from the README, whitepaper falsification logic, and MVP-PRD platform requirements on main. The Hermes failure-notification path is the one open decision blocking this from being final.