An open-source platform for educational resources and interactive learning.
- Create structured courses with documents, teacher collaboration and scheduled student access.
- Manage student and staff accounts, roles and promotions.
- Organize student groups and export attendance sheets.
- Plan timetables and oral examinations, with personal calendar subscriptions.
- Monitor account activity and educational resource usage.
- Frontend: SvelteKit, Bulma and TypeScript
- Backend: FastAPI and Python
- Database: PostgreSQL
- Containerization: Docker
frontend/— SvelteKit applicationbackend/— FastAPI applicationdocs/— Project documentationinfra/— Infrastructure configuration
After cloning the repository, run commands from its root. Install Docker with Linux containers and Compose v2. The revision-aware build also requires Git and Windows PowerShell 5.1+ (or PowerShell 7 on Linux). No host Python or Node installation is needed to run the Docker stack.
-
Create the local configuration, only for a new installation. Preserve any existing
.env.Windows PowerShell:
Copy-Item .env.example .envLinux shell:
cp -n .env.example .env
-
Edit
.env: setSOPHIKRON_SECRETS_DIRECTORYto an absolute private directory outside the repository. LeaveSOPHIKRON_ORIGIN=empty for localhost, keep the default ports unless they are occupied, and leave SMTP disabled. See the configuration variable reference for every setting, expected values, secret files and how changes take effect. -
Create all six secret files using the Windows or Linux instructions, then generate the identity keyring. These instructions generate independent passwords and an empty SMTP password file; secrets never belong in
.env. Keep the files for subsequent starts. -
Validate the configuration and start locally:
docker compose -f compose.yaml -f compose.local.yaml config --quiet ./build.ps1 -Local -Start
On Linux with PowerShell:
pwsh -File build.ps1 -Local -Start. Without PowerShell, use the existing Compose files directly:docker compose -f compose.yaml -f compose.local.yaml up -d --build --wait
Direct Compose builds show an unknown source revision. The application version still appears. Omit
-Startfrom the script to build only. See build options.
Open the application, sign in with setup_operator and the bootstrap
password, then complete /setup to create the permanent administrator. API docs are available at
localhost:8000/docs. The directory name is arbitrary; keep the same
Compose project name and secrets between starts to reuse your data.
Stop with docker compose -f compose.yaml -f compose.local.yaml down; volumes are preserved.
For manual trials, generate synthetic demo data after completing setup.
For automated tests, follow the development prerequisites and the
release verification commands:
cd backend
python run_tests.pyThis runner creates its own secrets, random ports and disposable database; it preserves the local installation. Frontend checks and optional browser journeys are described in the contribution guide.
See setup, secrets and migrations, authentication and recovery,
release checks, and the documentation index.
Production uses only compose.yaml and additionally needs HTTPS proxy configuration,
a public origin and backups. Do not use the local overlay in production.
Local test datasets can be generated with script/seed_demo_data.py; its central configuration
controls cohort sizes, staff, groups and annual timetables. See the demo data guide
for dry runs and separate test scenarios.
Contributions are welcome. Please read the contribution guidelines before submitting a pull request.
Bug reports and feature requests can be submitted through GitHub Issues.
Sophikron is free software distributed under the GNU General Public License v3.0.
Built for teachers, by contributors to open education.