diff --git a/docs/Deployment-Plan.md b/docs/Deployment-Plan.md index 66ec9b4..8a23b0d 100644 --- a/docs/Deployment-Plan.md +++ b/docs/Deployment-Plan.md @@ -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.* diff --git a/docs/Dev-Design.md b/docs/Dev-Design.md index 7a52cb5..58ced6d 100644 --- a/docs/Dev-Design.md +++ b/docs/Dev-Design.md @@ -513,7 +513,14 @@ Ollama daemon + 1B model requires ~2GB RAM. Running it inside the 150MB containe ### 11.2 MVP Security Baseline -- **Container hardening**: +> **Updated 2026-07-12:** Container-specific hardening below is *design intent*, not the current deployment. The live system runs as the `vpsadmin` standard user (no sudo) under Hermes cron. The equivalent protections that DO apply today: no hardcoded secrets (`.env` sourced by the pipeline scripts), DB file `chmod 600`, parameterized SQL. Container hardening is deferred to the future containerization task. + +- **Current (bare-script) baseline**: + - Runs as `vpsadmin` standard user (no sudo) + - Secrets in `/home/vpsadmin/oracle/.env` (`chmod 600`), never in code + - DB protected: `chmod 600 oracle.db` + - All outbound adapters use `https://` +- **Deferred (container) hardening** *(design intent, not live)*: - Run as non-root user (`user: nobody` in Dockerfile) - Read-only filesystem where possible (except `/tmp`, `/var/log`) - No SSH access inside container; pipeline is cron-triggered, no interactive access needed @@ -714,17 +721,20 @@ The following requirements are implied by this design and should be added to `do ### 16.1 CI Pipeline +> **Updated 2026-07-12:** CI originally built a Docker image per push. The live system has no CI/Docker build. The equivalent checks run manually/optionally: lint, `pip audit`, and `pytest` if tests exist. Container build is deferred. + On every push to `MVP-milestone`: - **Lint**: `ruff check`, `mdlint docs/` - **Test**: Run unit tests (`pytest tests/`), integration tests with seed dataset -- **Build**: Create Docker image, tag with commit SHA - **Scan**: Run `pip audit`; fail if critical vulnerabilities (>CVSS 7.0) found +- *(Deferred: Docker image build/tag with commit SHA)* ### 16.2 Deployment -- **Local dev**: `docker-compose up` (pipeline container + host-level Ollama) -- **Production**: `docker-compose up -d` + systemd services for inference (`qwythos-gpu0.service`) -- Ollama runs host-level (not in container) due to ~2GB memory requirement +> **Deployment reality (updated 2026-07-12):** This document originally specified Docker containerization (150MB cap, non-root, `python:3.11-slim`). The deployed system does **not** use containers. It runs as bare Python scripts under the `vpsadmin` standard user, invoked by Hermes cron (`oracle-pipeline.sh` at 13:00 UTC). The 150MB budget, non-root, and read-only-filesystem hardening described below remain *design intent* and are tracked as a future containerization task — not the current state. Ollama is also not deployed; summarization is deferred (graceful degradation is the live behavior). + +- **Local dev / Production**: Bare Python on the VPS, no Docker. `pip install` deps, run `schema.sql`, source `.env`, then Hermes cron drives `oracle-pipeline.sh`. +- **Ollama**: Not currently running. Pipeline stores raw text and defers summarization (see §10.2 / REQ-REL-25). Adding Ollama is a separate step, host-level. ### 16.3 Rollback Procedure