Tony_tech/athena-oracle
3
0
Fork 0
Code Issues 6 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: amend Dev-Design + Deployment-Plan to bare-script reality (no Docker)

Browse Source 
Decision 2026-07-12: do NOT containerize. Document actual deployment state:
- Bare Python scripts under vpsadmin user, Hermes cron drives oracle-pipeline.sh
- Container hardening / 150MB cap / Docker build retained as future target (design intent)
- Ollama not deployed; summarization deferred (graceful degradation is live)
- .env (chmod 600) is the live secret mechanism, not /etc/athena/secrets.yaml
This commit is contained in:
Epictetus
2026-07-12 06:55:27 +00:00
parent feba2fe7b7
commit 1539c743b5
2 changed files with 27 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Deployment-Plan.md
+12 -7
View File
@@ -1,20 +1,24 @@
# 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
- Docker installed on the target host
- 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
- 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
- *(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. Export required environment variables (`GITHUB_TOKEN`, `HUGGINGFACE_TOKEN`) — never hardcode these
5. 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 → summarize → score completes without errors before handing off to cron
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
@@ -35,8 +39,9 @@
## 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 Docker image
3. 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
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.*