Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
87 changes: 87 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Sophikron configuration template. Copy to .env for a new installation only.
# No passwords, tokens or encryption keys belong in this file.
# Compose reads .env; native Python processes read process environment only.
# Shell variables take precedence. Runtime variables are explicitly allowlisted in Compose.

# Application origin and published ports
# Local: leave the origin empty and open http://localhost:3000.
# FRONTEND_PORT also changes the default local origin. No trailing slash in explicit origins.
# Production: set an HTTPS origin before building; use only compose.yaml with a host proxy.
SOPHIKRON_ORIGIN=
FRONTEND_PORT=3000
# API and PostgreSQL ports are published on 127.0.0.1 only with compose.local.yaml.
BACKEND_PORT=8000
DB_PUBLISHED_PORT=5432

# Secret files and first installation
# Absolute host directory containing the six files listed in docs/database.md#generate-the-secrets.
# Forward slashes work on Windows. Protect this directory and preserve it between restarts.
SOPHIKRON_SECRETS_DIRECTORY=/absolute/path/to/private/sophikron
# Initial login name; its password comes from bootstrap_password in the secret directory.
AUTH_BOOTSTRAP_USERNAME=setup_operator

# PostgreSQL database and connection pool
DB_NAME=sophikron
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=5
# Timeouts are seconds unless suffixed _MS.
DB_POOL_TIMEOUT=5
DB_POOL_RECYCLE=1800
DB_CONNECT_TIMEOUT=5
DB_STATEMENT_TIMEOUT_MS=10000
DB_LOCK_TIMEOUT_MS=2000
DB_IDLE_TRANSACTION_TIMEOUT_MS=30000
DB_HEALTH_TIMEOUT=2

# Authentication sessions (seconds)
# The local overlay enables HTTP cookies; production forces secure cookies and HTTPS origins.
AUTH_SESSION_SECONDS=28800
AUTH_IDLE_SECONDS=1800

# Login throttling and password hashing admission
# Failure budgets per IP and per IP/identifier; fixed window and reservation lease in seconds.
AUTH_LOGIN_IP_LIMIT=20
AUTH_LOGIN_IDENTITY_LIMIT=5
AUTH_RATE_WINDOW_SECONDS=900
AUTH_LOGIN_RESERVATION_SECONDS=120
AUTH_PASSWORD_QUEUE_SIZE=8
AUTH_PASSWORD_QUEUE_TIMEOUT_SECONDS=5

# Authentication HTTP request limits (bytes and seconds)
# Binary document uploads have their own per-format size and transfer limits.
AUTH_REQUEST_MAX_BYTES=16384
AUTH_REQUEST_BODY_TIMEOUT_SECONDS=10

# Private document storage (bytes)
# Docker fixes the document root to the writable documents_data volume.
DOCUMENT_COURSE_QUOTA_BYTES=1073741824
DOCUMENT_USER_QUOTA_BYTES=5368709120
DOCUMENT_TOTAL_QUOTA_BYTES=21474836480
DOCUMENT_RESERVE_BYTES=268435456
# Active downloads per backend process; additional requests wait.
DOCUMENT_MAX_CONCURRENT_DOWNLOADS=16

# Calendar subscription feeds
AUTH_CALENDAR_FEED_LIMIT_PER_MINUTE=5

# Invitations and email delivery
# Leave mail disabled for local trials; administrators can share invitation links manually.
AUTH_MANUAL_INVITATIONS_ENABLED=true
AUTH_MAIL_TRANSPORT=disabled
# For SMTP, set host, sender and activation URL (e.g. http://localhost:3000/activate locally).
# Production activation URLs require HTTPS. Use starttls (587) or tls (465) as appropriate.
# If SMTP authentication is required, set the username and fill the smtp_password secret file.
AUTH_SMTP_HOST=
AUTH_SMTP_PORT=587
AUTH_SMTP_SECURITY=starttls
AUTH_SMTP_USERNAME=
AUTH_SMTP_SENDER=
AUTH_ACTIVATION_URL=

# Optional Docker network overrides: change these three together if the subnet conflicts.
# BFF_SUBNET=172.30.85.0/24
# BFF_ADDRESS=172.30.85.2
# API_ADDRESS=172.30.85.3

# Build metadata is generated by build.ps1, not stored here.
# Direct Compose builds without an explicit revision display an unknown revision.
39 changes: 39 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@

version: 2

updates:
# Backend — Python
- package-ecosystem: "pip"
directory: "/backend"
schedule:
interval: "monthly"
time: "09:00"
timezone: "Europe/Paris"
target-branch: "develop"
open-pull-requests-limit: 1
groups:
backend-dependencies:
patterns:
- "*"

# Frontend — npm
- package-ecosystem: "npm"
directory: "/frontend"
schedule:
interval: "monthly"
time: "09:00"
timezone: "Europe/Paris"
target-branch: "develop"
open-pull-requests-limit: 1
groups:
frontend-dependencies:
patterns:
- "*"

ignore:
- dependency-name: "typescript"
update-types:
- "version-update:semver-major"
- dependency-name: "@types/node"
update-types:
- "version-update:semver-major"
49 changes: 36 additions & 13 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,14 @@

on:
push:
branches:
- main
- develop

pull_request:
branches:
- main
- develop

permissions:
contents: read
Expand Down Expand Up @@ -41,42 +48,52 @@ jobs:
umask 077
secret_dir="$RUNNER_TEMP/sophikron-db-secrets"
mkdir -p "$secret_dir"
openssl rand -hex 32 > "$secret_dir/bootstrap_password"
touch "$secret_dir/smtp_password"
chmod 0444 "$secret_dir/bootstrap_password" "$secret_dir/smtp_password"
echo "SOPHIKRON_SECRETS_DIRECTORY=$secret_dir" >> "$GITHUB_ENV"
echo "AUTH_BOOTSTRAP_USERNAME=ci_setup" >> "$GITHUB_ENV"
for role in admin app migration; do
openssl rand -hex 32 > "$secret_dir/$role"
chmod 0444 "$secret_dir/$role"
openssl rand -hex 32 > "$secret_dir/db_${role}_password"
chmod 0444 "$secret_dir/db_${role}_password"
done
echo "DB_ADMIN_SECRET_PATH=$secret_dir/admin" >> "$GITHUB_ENV"
echo "DB_APP_SECRET_PATH=$secret_dir/app" >> "$GITHUB_ENV"
echo "DB_MIGRATION_SECRET_PATH=$secret_dir/migration" >> "$GITHUB_ENV"
encryption_key=$(openssl rand -base64 32)
lookup_key=$(openssl rand -base64 32)
printf '{"active_key":"ci","encryption_keys":{"ci":"%s"},"lookup_key":"%s"}\n' \
"$encryption_key" "$lookup_key" > "$secret_dir/identity_keys.json"
chmod 0444 "$secret_dir/identity_keys.json"
echo "DB_NAME=sophikron_test" >> "$GITHUB_ENV"
echo "DB_HOST=127.0.0.1" >> "$GITHUB_ENV"
echo "DB_PORT=5432" >> "$GITHUB_ENV"
echo "DB_USER=sophikron_app" >> "$GITHUB_ENV"
echo "DB_PASSWORD_FILE=$secret_dir/app" >> "$GITHUB_ENV"
echo "DB_TEST_MIGRATION_PASSWORD_FILE=$secret_dir/migration" >> "$GITHUB_ENV"
echo "DB_PASSWORD_FILE=$secret_dir/db_app_password" >> "$GITHUB_ENV"
echo "DB_TEST_MIGRATION_PASSWORD_FILE=$secret_dir/db_migration_password" >> "$GITHUB_ENV"
echo "DB_TEST_API_URL=http://127.0.0.1:8000" >> "$GITHUB_ENV"
echo "AUTH_ENVIRONMENT=development" >> "$GITHUB_ENV"
echo 'AUTH_ALLOWED_ORIGINS=["http://localhost:3000","http://localhost:8000"]' >> "$GITHUB_ENV"
echo "AUTH_COOKIE_SECURE=false" >> "$GITHUB_ENV"

- name: Validate Compose configuration
working-directory: .
run: docker compose config --quiet
run: docker compose -f compose.yaml -f compose.local.yaml config --quiet

- name: Start full PostgreSQL and API services
working-directory: .
timeout-minutes: 15
run: |
docker compose -p sophikron-ci up -d --build --wait db backend
docker compose -p sophikron-ci run --build --rm migrate
docker compose -f compose.yaml -f compose.local.yaml -p sophikron-ci up -d --build --wait db backend

- name: PostgreSQL integration tests
env:
DB_INTEGRATION: "1"
run: python -m pytest -q -m integration

- name: Stop verification services
if: always()
# Earlier failures can skip secret preparation; Compose down also needs this path.
if: ${{ always() && env.SOPHIKRON_SECRETS_DIRECTORY != '' }}
working-directory: .
run: >-
docker compose -p sophikron-ci down
docker compose -f compose.yaml -f compose.local.yaml -p sophikron-ci down

frontend:
name: Frontend checks
Expand All @@ -92,7 +109,7 @@ jobs:
- name: Set up Node.js
uses: actions/setup-node@v5
with:
node-version: "22"
node-version: "24"
cache: npm
cache-dependency-path: frontend/package-lock.json

Expand All @@ -105,5 +122,11 @@ jobs:
- name: Check Svelte and TypeScript
run: npm run check

- name: Install Chromium for browser security tests
run: npx playwright install --with-deps chromium

- name: Test BFF security boundaries
run: npm test

- name: Build frontend
run: npm run build
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ env/
# Environment variables and secrets
.env
.env.*
!.env.example
secrets/
credentials/
*.pem
*.key
Expand Down
6 changes: 5 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ did.

## 9. Dependencies and documentation

- Keep the README accurate for setup, configuration, development and testing.
- Do not update README.md unless explicitly requested to do so.
- Before adding significant dependencies, external services or paid infrastructure, explain the purpose, alternatives,
maintenance, licensing, security and cost implications; obtain approval when the choice is consequential.
- Document lasting architectural decisions and relevant API behavior concisely.
Expand All @@ -143,3 +143,7 @@ necessary migrations and documentation are updated, and security implications ha
verification results and remaining limitations.

Completing one increment does not authorize starting the next major phase when review or approval is required.

- Reuse existing configuration and infrastructure files; do not create duplicate Compose files, environment templates or scripts without justification and approval.
- Before adding files, inspect existing equivalents, including local `.env` files, without exposing or modifying their secrets.
- Before finishing, clean up temporary files, unused code and artifacts created by the task; preserve pre-existing files and user changes.
128 changes: 128 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Contributing to Sophikron

Thank you for your interest in contributing to Sophikron.

## How to contribute

1. Check existing issues before reporting a bug or proposing a feature.
2. Open an issue to discuss significant changes before implementing them.
3. Keep changes focused and avoid unrelated modifications.
4. Follow the project conventions documented in `AGENTS.md`.
5. Add or update tests when changing application behavior.
6. Update documentation when necessary.

## Pull requests

A pull request should:

- Explain the purpose of the changes.
- Describe the main implementation choices.
- Include tests or explain why they are not applicable.
- Pass the relevant tests, linting and build checks.
- Contain no secrets, credentials or unrelated generated files.

Use the pull request template provided in `.github/PULL_REQUEST_TEMPLATE.md`.

## Code quality

- Prefer simple, readable and maintainable code.
- Document functions and methods in English.
- Follow the formatting and linting rules configured for each component.
- Validate user input and enforce authorization on the backend.
- Treat user-provided JavaScript as untrusted code.

## Verification before a release

Use the Python interpreter configured for the project and the existing package scripts.
From `backend/`:

```sh
python -m pytest -q
ruff check . ../script
python run_tests.py
```

The first command skips PostgreSQL integration tests unless a dedicated test database is configured.
The existing `run_tests.py` launcher runs the complete suite, including migration rollback,
reapplication and SQLAlchemy metadata comparison, in a disposable Docker Compose project with
synthetic secrets. Docker Desktop must be running. It reuses the project Compose files, keeps the
development `.env` and persistent database untouched, and removes only its own test services and
volumes. See [database verification](docs/database.md#verification) for configuration and manual subsets.

From `frontend/`:

```sh
npm test
npm run check
npm run lint
npm run build
node --test tests/timetable-browser.mjs
```

On Windows PowerShell, use `npm.cmd` when the execution policy blocks `npm.ps1`.
The TypeScript test runner requires Node 22.6 or newer; Node 24 is also supported.
The timetable browser scenario uses the built frontend and a synthetic HTTP backend. It checks
calendar management, event editing, recurrence confirmations, staff availability and mobile access.
It complements the PostgreSQL authorization tests. Playwright needs an installed browser; no browser
is downloaded automatically.

For the real BFF journey, set `BFF_INTEGRATION=1` before running `python run_tests.py`.
Add `BFF_BROWSER_INTEGRATION=1` for desktop/mobile UI checks. The default channel is installed Edge;
`BFF_BROWSER_CHANNEL` selects another installed channel. `BROWSER_EXECUTABLE` selects the executable
for the native form regression in `npm test`, which otherwise skips if no compatible browser exists.
`BFF_SCREENSHOTS_DIRECTORY` optionally captures the synthetic overview. Use only synthetic test data
for these captures. The real BFF journeys refuse targets outside the disposable test environment.

Report the commands run, their actual results, skipped checks and remaining limitations. Passing
checks alone does not establish production readiness or comprehensive security.

## Documentation ownership

Keep each operational subject in one reference and link to it from related feature documents:

| Subject | Reference |
| --- | --- |
| Verification commands and release checks | This document |
| PostgreSQL, migration history and database operations | [database.md](docs/database.md) |
| Annual timetables, audiences, diagnostics and ICS | [timetable.md](docs/timetable.md) |
| Local demo scenario and API-only seeding | [timetable demo data](docs/timetable.md#local-demo-data) |
| Identities, sessions, keys and account recovery | [authentication.md](docs/authentication.md) |
| Accounts, promotion partitions and activity journal | [administration.md](docs/administration.md) |
| Subjects and public site configuration | [administration.md](docs/administration.md) |
| Frontend/BFF boundaries and deployment | [frontend-bff.md](docs/frontend-bff.md) |
| Course content and private files | [lessons.md](docs/lessons.md) |
| Pedagogical statistics | [statistics.md](docs/statistics.md) |

Keep `/docs` focused on architecture, component contracts and deployment design, written in English.
Keep contribution and release verification instructions in this root-level guide.
Do not add temporary security reviews, audit reports or implementation diaries to `/docs`.

## Button design contract

Use the shared rules in `frontend/src/app.css`; do not introduce local button palettes, borders,
hover effects or shadows. The three variants are filled primary (`button is-primary`), secondary
(`button`, optionally `is-light`), and quiet (`button is-text`). Icon-only controls use the shared
`icon-button` geometry; navigation and selection controls use the quiet variant.
Secondary and icon controls use a subtle gradient and thin tinted border. The shared `--action-tone`
drives both resting and hover gradients, including warning/danger tones; never hard-code a primary
hover for semantic actions. Filled primary actions remain solid and graph legends remain borderless.
Warning (`button is-warning`) and danger (`button is-danger`) are semantic tones with the same
geometry, motion and focus rules. Every danger action must open a confirmation first, or be the
explicit confirmation button inside an already-open dialog/panel. Informational warning controls
must not use danger styling. Retain disabled/loading states, accessible labels and reduced-motion
support. Check text contrast at rest and on hover in light and dark themes.
Chart visibility legends use the dedicated borderless soft-background `chart-toggle` variant;
keep it independent of pressed-button primary styling. Subject/promotion cards use neutral surfaces
with subtle assigned-color tints, a bounded subject emblem or promotion swatch, and neutral readable
labels. Emblems use an automatically contrasting foreground. Semantic warning and danger
tones take precedence over the secondary `is-light` treatment.

## Licensing

By contributing, you agree that your contributions will be distributed under the project's GNU General Public License v3.0, in accordance with the license terms.

## Questions

Use GitHub Discussions for questions and general discussions, when available. Use issues for bug reports and feature requests.

For builds containing local commits or uncommitted changes, use the [revision-aware build script](docs/database.md#building-images-with-revision-metadata). A modified build is labelled explicitly in the dashboard.
Loading
Loading