feat(M15): README, README.LLM.md, LICENSE, CHANGELOG, and final cleanup
Complete the M15 documentation and final review milestone: README.md (French, brief): - Project description, quick start, usage, deployment link, acknowledgments - Acknowledgments: pronotepy, icalendar, caldav, slixmpp, pydantic, openai, feedparser, beautifulsoup4, and inspiration from pronote-digest (Antoine Coulon) - Author: Antoine Van Elstraete README.LLM.md (English, AI agent guide): - Prerequisites, installation on LXC/VPS (Debian/CentOS) - Non-secret configuration preparation (all env vars listed) - Secret variables clearly identified as operator-only - Pre-deployment checks (check_secrets.py, pip check, dry-run) - systemd/timer/logrotate installation steps - Notes for AI agent (do not commit secrets, do not modify existing files) LICENSE: - Standard MIT License, copyright Antoine Van Elstraete (2026) CHANGELOG.md: - Initial changelog following Keep a Changelog format - Covers M1 through M14 with milestone summaries - Gitea Actions noted as planned/optional, not delivered .gitignore: - Added FEAT_* pattern for temporary work files TODO.md: - M15 items 1-4 checked (README, architecture docs, CHANGELOG+LICENSE, final review) - M15 item 5 (Gitea Actions) left unchecked (optional, not done) Co-authored-by: opencode/tech-writer <tech-writer@agents.invalid>
This commit is contained in:
147
README.LLM.md
Normal file
147
README.LLM.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# pronote-sync — AI Agent Setup Guide
|
||||
|
||||
This document guides an AI agent through installing and pre-configuring the `pronote-sync` project on a fresh Linux host (Debian/CentOS). It covers environment setup, dependency installation, and configuration file preparation. It does **NOT** cover secrets provisioning — those must be provided by the operator.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python ≥ 3.13.5 (check with `python3 --version`)
|
||||
- Git
|
||||
- A non-root service user (e.g., `pronote-sync`)
|
||||
- Target paths:
|
||||
- `/opt/pronote-sync` (code)
|
||||
- `/var/lib/pronote-sync` (state)
|
||||
- `/var/log/pronote-sync` (logs)
|
||||
- `/etc/pronote-sync` (config)
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
```bash
|
||||
# Create service user
|
||||
sudo useradd --system --no-create-home --shell /usr/sbin/nologin pronote-sync
|
||||
|
||||
# Clone the repository
|
||||
sudo git clone <repo-url> /opt/pronote-sync
|
||||
sudo chown -R pronote-sync:pronote-sync /opt/pronote-sync
|
||||
|
||||
# Create virtual environment
|
||||
cd /opt/pronote-sync
|
||||
sudo -u pronote-sync python3.13 -m venv .venv
|
||||
sudo -u pronote-sync .venv/bin/pip install -e ".[dev]"
|
||||
|
||||
# Create directories
|
||||
sudo install -d -m 0700 -o pronote-sync -g pronote-sync /etc/pronote-sync
|
||||
sudo install -d -m 0750 -o pronote-sync -g pronote-sync /var/lib/pronote-sync
|
||||
sudo install -d -m 0750 -o pronote-sync -g pronote-sync /var/log/pronote-sync
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Preparation (Without Secrets)
|
||||
|
||||
```bash
|
||||
# Copy the example config
|
||||
sudo -u pronote-sync cp /opt/pronote-sync/.env.example /etc/pronote-sync/pronote-sync.env
|
||||
|
||||
# The operator must fill in secrets (PRONOTE_PASSWORD, CALDAV_PASSWORD, XMPP_PASSWORD, AI_API_KEY, etc.)
|
||||
# Do NOT populate secrets automatically — leave them for the operator.
|
||||
```
|
||||
|
||||
### Non-Secret Environment Variables (Pre-Configurable)
|
||||
|
||||
The following variables can be safely pre-configured in `/etc/pronote-sync/pronote-sync.env`:
|
||||
|
||||
- **Pronote:**
|
||||
- `PRONOTE_ACCOUNT_TYPE` (default: `parent`)
|
||||
- `PRONOTE_ENT` (ENT slug, e.g., `lyceeconnecte`)
|
||||
- `PRONOTE_AGENDA_SOURCE`, `PRONOTE_HOMEWORK_SOURCE`, `PRONOTE_MESSAGES_SOURCE` (`auto`, `ical`, or `pronotepy`)
|
||||
|
||||
- **CalDAV:**
|
||||
- `CALDAV_CALENDAR_PATH` (e.g., `/pronote-sync/`)
|
||||
- `CALDAV_ALLOW_INSECURE_HTTP` (default: `false`)
|
||||
|
||||
- **Sync Window:**
|
||||
- `SYNC_PAST_DAYS`, `SYNC_FUTURE_DAYS`
|
||||
|
||||
- **Theoretical Agenda:**
|
||||
- `THEORETICAL_AGENDA_PATH`, `SCHOOL_HOLIDAYS_PATH`
|
||||
- `THEORETICAL_WEEK_ANCHOR_DATE`, `THEORETICAL_WEEK_ANCHOR_TYPE`
|
||||
|
||||
- **XMPP:**
|
||||
- `XMPP_ENABLED`, `XMPP_HOST`, `XMPP_PORT`, `XMPP_USE_TLS`, `XMPP_TIMEOUT`, `XMPP_RESOURCE`
|
||||
|
||||
- **AI:**
|
||||
- `AI_ENABLED`, `AI_PROVIDER`, `AI_BASE_URL`, `AI_MODEL`, `AI_ALLOW_INSECURE_HTTP`
|
||||
|
||||
- **Blog:**
|
||||
- `BLOG_ENABLED`, `BLOG_RSS_URL`
|
||||
|
||||
- **General:**
|
||||
- `DRY_RUN`, `LOG_LEVEL`
|
||||
|
||||
### Secret Variables (Operator Must Provide)
|
||||
|
||||
**Do NOT set these variables automatically.** The operator must manually provide the following secrets:
|
||||
|
||||
- **Pronote:**
|
||||
- `PRONOTE_ICAL_URL`, `PRONOTE_URL`, `PRONOTE_USERNAME`, `PRONOTE_PASSWORD`
|
||||
|
||||
- **CalDAV:**
|
||||
- `CALDAV_URL`, `CALDAV_USERNAME`, `CALDAV_PASSWORD`
|
||||
|
||||
- **XMPP:**
|
||||
- `XMPP_JID`, `XMPP_PASSWORD`, `XMPP_TO`
|
||||
|
||||
- **AI:**
|
||||
- `AI_API_KEY`
|
||||
|
||||
---
|
||||
|
||||
## Pre-Deployment Checks
|
||||
|
||||
```bash
|
||||
# Verify no secrets in the codebase
|
||||
/opt/pronote-sync/.venv/bin/python /opt/pronote-sync/scripts/check_secrets.py
|
||||
|
||||
# Verify dependencies
|
||||
/opt/pronote-sync/.venv/bin/python -m pip check
|
||||
|
||||
# Dry-run test (will fail without secrets, but verifies the environment)
|
||||
/opt/pronote-sync/.venv/bin/pronote-sync --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## systemd Installation
|
||||
|
||||
```bash
|
||||
# Install systemd units
|
||||
sudo install -m 0644 /opt/pronote-sync/deploy/systemd/pronote-sync.service /etc/systemd/system/
|
||||
sudo install -m 0644 /opt/pronote-sync/deploy/systemd/pronote-sync.timer /etc/systemd/system/
|
||||
|
||||
# Install logrotate config
|
||||
sudo install -m 0644 /opt/pronote-sync/deploy/logrotate/pronote_sync /etc/logrotate.d/pronote_sync
|
||||
|
||||
# Reload and enable
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now pronote-sync.timer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes for the AI Agent
|
||||
|
||||
- **Do NOT commit or write secrets** to any file in the repository.
|
||||
- **Do NOT modify** `.gitignore`, `pyproject.toml`, or existing source files.
|
||||
- If `python3.13` is not available, install it first:
|
||||
- Debian: `sudo apt install python3.13`
|
||||
- CentOS: Compile from source or use `dnf` if available.
|
||||
- The `check_secrets.py` script exits with:
|
||||
- `0` (clean)
|
||||
- `1` (secrets found)
|
||||
- `2` (error)
|
||||
- All paths in the systemd unit assume `/opt/pronote-sync` — adjust if installed elsewhere.
|
||||
- The operator **must** provide real values for all **SECRET** variables before enabling the timer.
|
||||
Reference in New Issue
Block a user