An open-source school administration platform built from real classroom experience.
Your students' records belong to your institution—not to a vendor subscription.
Why KoAkademy · The Platform · Stack · Quick Start · Operate It · Contributing
Warning
KoAkademy is beta software and is not yet recommended for production use. Pre-v2 releases can contain breaking changes or incompatible upgrades. Evaluate it in staging, keep tested backups, and review the security guidance before storing institutional data.
KoAkademy started in 2023 as a college feasibility project here in the Philippines. Back then, my groupmates and I were just students trying to solve a real problem at our school: the existing systems were either too expensive, too rigid, or simply not built for how Philippine schools actually operate. We wrote the first version in vanilla PHP. In 2024, we rebuilt it on Laravel. After graduation, I kept going—alone at first, then with the help of tools like Codex, and now as a working developer.
The system went live at our school and has been running there ever since. Today, two schools use it as part of their core infrastructure. I have never charged for it. I am not great at closing deals, and honestly, I have never been paid for this project. I just wanted to help my school innovate, even a little.
That is why I open-sourced it. If your institution cannot afford a commercial SIS or LIS, you should still have access to a system that respects your data and your budget.
School software holds more than a timetable. It holds student identities, grades, tuition, medical records, attendance, and years of institutional history. When that system is a hosted product, the school inherits someone else'"'"'s pricing, roadmap, retention policy, and operational decisions.
KoAkademy takes a different position: the institution should own the system of record. It is a complete school administration and learning platform that runs on infrastructure you choose. The PostgreSQL database, object storage, backups, domains, and upgrade schedule are yours to manage and audit.
No per-student pricing. No feature gates hidden behind a sales call. Just a tool that works.
Yes, this project is only half complete. But it is usable today, and it is already helping real schools. If you have suggestions, improvements, or just want to rant about a bug you found, you are always welcome. And if KoAkademy has been useful to you, a star on the repository goes a long way—it keeps me motivated to continue.
Feel free to try it and share feedback. Even the harsh kind. I appreciate every single one.
Every feature and data model in KoAkademy is shaped by the day-to-day workflow of real Philippine schools. The enrollment flow, grading schema, finance structure, and registrar processes reflect how schools here actually operate—which can differ quite a bit from what you might call "standard" international practice.
If you are from another country and find that our data schema or school operations do not quite match yours, pull requests are genuinely appreciated. I would love to make KoAkademy flexible enough to support schools worldwide, but I can only build for what I know. Your input helps us all.
Enrollment — track applicants, verification status, balances, and the registrar workflow in one place. |
Academics — manage sections, capacity, curricula, and schedules with the school context intact. |
Finance — assess tuition, receive payments, and issue records without exporting student data to another product. |
Library — catalogue physical holdings and publish rights-cleared digital editions through a controlled reader. |
KoAkademy is built around the daily work of a school, not a generic database with education fields added later.
| Administration | Students, faculty, programs, courses, classrooms, terms, schedules, attendance, grading, reports, and institution branding. |
| Enrollment | A registrar-to-cashier workflow driven by versioned enrollment blueprints. Rules can be scoped, simulated, staged, and rolled back instead of being buried in code. |
| Three portals | Distinct administrator, faculty, and student experiences for the work each role actually needs: classes, attendance, submissions, grades, schedules, tuition, announcements, and digital IDs. |
| Finance | Tuition assessment, payment posting, statements of account, receipts, public verification, and finance reporting. |
| Optional modules | Library, inventory, cashier, student medical records, announcements, notification tools, and standalone workflows such as Forms can be enabled as the institution needs them. |
| Security and accountability | Role-based permissions, multi-factor authentication, passkeys, audited impersonation, and an operator-controlled deployment boundary. |
The public API is intentionally small while it is beta. Only the endpoints described in the API documentation are part of its supported contract.
Enrollment is where a school’s rules become visible: who can enrol, which documents they need, which checks must happen before payment, what tuition applies, and when an account becomes active. Those are institutional policies, not constants that should require a deployment to change.
KoAkademy models them as versioned blueprints with inheritance, availability and eligibility checks, academic and billing gates, approvals, notifications, simulations, staged publication, and rollback. The result is a workflow a registrar can understand and an institution can adapt without losing its audit trail. Read the blueprint overview for the model and the quick start to configure one.
A Laravel application with a React portal layer, packaged for self-hosting rather than split across vendor services.
| Application | Laravel 13 · PHP 8.5 · Filament 5 |
| Portals | Inertia v3 · React 19 · TypeScript · Vite 8 |
| Data and jobs | PostgreSQL · Redis · Laravel queues, cache, sessions, and scheduled work |
| Documents | Gotenberg for PDFs · S3-compatible object storage for uploads |
| Runtime | nginx + PHP-FPM in a Docker image, with a FrankenPHP (Octane) variant · Docker Swarm installer or supported Docker Compose topology |
| Quality | Pest 5 · Laravel Pint · frontend and documentation builds · CI validation |
| Area | Supported baseline |
|---|---|
| Production host | Linux with Docker Engine and a public DNS name |
| CPU architectures | AMD64 and ARM64 |
| Application runtime | PHP 8.5, Laravel 13, Filament 5 |
| Databases | PostgreSQL in production; SQLite for local development and tests |
| Application services | Redis queues/cache/sessions and Gotenberg for production PDF rendering |
| Alternative deployment | Docker Compose for operators managing their own reverse proxy |
Optional domains are published as Composer packages from the signed KoAkademy module registry:
composer config repositories.koakademy composer https://yukazakiri.github.io/koakademy-modules
composer require koakademy/library-system:^1.0The core scans vendor-installed modules by default. The registry client is signature-checked and read-only; installations remain explicit Composer operations. The Marketplace can enable an installed module, but it does not install packages or update a running container. A container-hosted registry can generate its Ed25519 keypair on first deployment with its persistent key volume. Never commit the private key. See the module registry deployment guide for release and update procedures.
Regulatory reports use an adapter contract and configuration registry so compatible providers can be added by contributors or modules. Only CHED E-Form B/C is built in and supported by this release; other jurisdictions require an explicit provider implementation and installation. See the Regulatory Report Provider guide.
| Path | |
|---|---|
app/ |
Laravel application services, models, policies, jobs, and HTTP boundaries |
resources/js/ |
Inertia React pages and shared portal components |
Modules/ |
Optional domain modules |
database/ |
Migrations, factories, and seeders |
docker/ |
Production image and runtime processes |
docs/ |
Operator, maintainer, API, and staff documentation |
tests/ |
Pest feature and unit coverage |
The supported production installer is Linux-only. It installs Docker when needed, preserves or creates a single-node Swarm manager, creates an attachable overlay network, deploys Caddy HTTPS with PostgreSQL, Redis, Gotenberg, and a private FrankenPHP application, then opens the one-time /setup wizard.
Linux
curl -fsSL https://github.com/yukazakiri/koakademy/releases/latest/download/install.sh | bashThe stable installer resolves the latest checksummed release by default.
Provide the public hostname through KOAKADEMY_DOMAIN for a non-interactive
install:
curl -fsSL https://github.com/yukazakiri/koakademy/releases/latest/download/install.sh \
| env KOAKADEMY_DOMAIN=koakademy.koamishin.com bashThe installer requests root privileges only for Docker, Swarm, and
/opt/koakademy operations, so the command can be run as your normal Linux
user when sudo is available. It adds that user to Docker's docker group;
log out and back in, or run newgrp docker, before using docker without
sudo. Docker-group membership grants root-equivalent access to the host.
Before using a public hostname, point its DNS A record to the VPS and allow
inbound TCP ports 80 and 443. Caddy obtains and renews HTTPS certificates for
that hostname. For the example domain, the application will be available at
https://koakademy.koamishin.com, with administration at /admin and the
one-time setup wizard at /setup.
The https://dokploy.com/install.sh command installs Dokploy itself. It is not
the KoAkademy installer and must not be used in place of the command above.
Visit /setup when the installer finishes to create the institution, the first academic period, and the first super administrator. The setup route closes after initialization.
The installer runs privileged remote code. Inspect it first if that is not appropriate for your environment:
curl -fSLO https://github.com/yukazakiri/koakademy/releases/latest/download/install.sh
less install.sh
env KOAKADEMY_DOMAIN=school.example bash install.shTo evaluate the unreleased master build without a domain, use the edge
channel. It resolves the current master commit, downloads the matching
operator and Swarm assets, and publishes the app on port 8000 using the
mutable edge-frankenphp image. Open http://127.0.0.1:8000/setup after it
finishes, or choose another port with --port. This path is for staging and
development only; it can change or break without a stable release:
curl -fsSL https://raw.githubusercontent.com/yukazakiri/koakademy/master/scripts/install.sh | bash -s -- edgeStable releases publish the bootstrap, operator command, domain-backed and
direct-port Swarm bundles, runtime configuration, image metadata, and
SHA256SUMS together. The installer refuses
to continue when the downloaded release assets do not verify as a complete
bundle.
For a manually managed deployment, use Getting Started. It covers the supported Docker Compose topology, explicit migrations, S3-compatible storage, and the reverse-proxy requirements.
For local development and verification, follow Development and run the documented checks in Contributing. The documentation and local-link check can be run independently with:
npm run docs:checkRun a current stable release in production. Caddy owns ports 80/443; the application, PostgreSQL, Redis, and Gotenberg stay private. Use koakademy update for an explicit backed-up release update and koakademy configure storage|mail|search for Docker-Secret-backed provider changes. The operator self-elevates when it needs root-owned runtime files.
| Need | Start here |
|---|---|
| Install, configure, or upgrade a server | Getting Started · Deployment · Configuration |
| Plan backups, HTTPS, storage, or recovery | Deployment runbook · Self-hosting FAQ |
| Understand the codebase and run it locally | Development · Architecture guide |
| Configure enrollment policies | Enrollment blueprints |
| Use the administrator, faculty, or student portals | Staff user guide |
| Integrate with the supported API | API overview |
The hosted documentation site, when enabled for the repository, is available at yukazakiri.github.io/koakademy.
Contributions are welcome when they are focused, tested, and safe for self-hosting institutions. Start with CONTRIBUTING.md. To report a vulnerability, use a private GitHub Security Advisory—not a public issue—and follow SECURITY.md.
KoAkademy is licensed under the GNU AGPL-3.0-or-later. If people use a modified version over a network, they must be able to obtain that modified source. The code that handles a school’s records should remain available to the people who depend on it.