docs: amend Dev-Design + Deployment-Plan to bare-script reality (no Docker)
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:
+12
-7
@@ -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.*
|
||||
|
||||
+15
-5
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user