college-infos/README.LLM.md

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

# 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)

# 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_TLS_MODE, XMPP_TIMEOUT, XMPP_CONNECT_TIMEOUT, XMPP_CLEANUP_TIMEOUT, XMPP_RESOURCE
  • XMPP_USE_TLS is deprecated but still supported (aliased to XMPP_TLS_MODE)

• 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

# 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

# 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.