https://github.com/yukazakiri/koakademy

🎓 Modern open-source and opinionated academic management platform for student lifecycle workflows. Built with Laravel 12, Inertia.js, React & Tailwind CSS. Features enrollment, billing, scheduling & admin tools with configurable branding and PWA support.
https://github.com/yukazakiri/koakademy

academic-management admin-dashboard agpl college education enrollment erp filamentphp inertiajs laravel open-source php postgresql pwa react school-management student-information-system tailwindcss university

Last synced: 27 days ago
JSON representation

🎓 Modern open-source and opinionated academic management platform for student lifecycle workflows. Built with Laravel 12, Inertia.js, React & Tailwind CSS. Features enrollment, billing, scheduling & admin tools with configurable branding and PWA support.

• Host: GitHub
• URL: https://github.com/yukazakiri/koakademy
• Owner: yukazakiri
• License: other
• Created: 2026-04-09T08:56:07.000Z (3 months ago)
• Default Branch: master
• Last Pushed: 2026-06-02T04:00:03.000Z (30 days ago)
• Last Synced: 2026-06-02T05:22:42.109Z (30 days ago)
• Topics: academic-management, admin-dashboard, agpl, college, education, enrollment, erp, filamentphp, inertiajs, laravel, open-source, php, postgresql, pwa, react, school-management, student-information-system, tailwindcss, university
• Language: PHP
• Homepage: https://yukazakiri.github.io/koakademy/
• Size: 9.01 MB
• Stars: 2
• Watchers: 0
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

          



[![Contributors][contributors-shield]][contributors-url]

[![Forks][forks-shield]][forks-url]

[![Stargazers][stars-shield]][stars-url]

[![Issues][issues-shield]][issues-url]

[![AGPLv3 License][license-shield]][license-url]






  

    

  


  
KoAkademy


  


    KoAkademy is an academic management platform that keeps student records, enrollment, billing, schedules, and school administration together in one application.

    


    Built for schools, staff, and developers, it combines a polished web experience with a modern backend stack.

    


    Explore the docs »

    


    


    View Demo

    ·

    Report Bug

    ·

    Request Feature

  



  Table of Contents

  


    


      About The Project

      


        
Built With

      

    

    


      Getting Started

      


        
Quick Start

      

    

    
Deployment

    
Development

    
Usage

    
Roadmap

    
Contributing

    
License

    
Acknowledgments

  


## About The Project

![KoAkademy][product-screenshot]

KoAkademy is an academic management system made to simplify school operations for administrators, teachers, and students.

It brings admissions, tuition, schedules, reporting, and school settings into one place so teams can work without switching tools.

The platform is built with Laravel 12, Inertia + React, Filament, and Tailwind CSS, giving developers a modern codebase and users a fast, intuitive interface.

### Key Features

* **Student Management** — Enrollment, records, and lifecycle tracking in one dashboard.

* **Financial Management** — Billing, tuition payments, fee structures, and financial reporting.

* **Schedule Management** — Class schedules, timetables, and room assignments.

* **Admin Dashboard** — Comprehensive staff tooling for school operations and configuration.

* **Student Portal** — Self-service access to grades, schedules, billing, and school information.

* **Customizable Branding** — Logo, favicon, colors, and metadata configurable without code.

* **Extensible Architecture** — Built on modern Laravel with reusable components and modules.

* **Progressive Web App** — Works offline-first with install-to-home-screen support.

(back to top)


### Built With

* [![Laravel][Laravel.com]][Laravel-url]

* [![Inertia][Inertia.shield]][Inertia-url]

* [![React][React.js]][React-url]

* [![Tailwind CSS][Tailwind.shield]][Tailwind-url]

* [![PostgreSQL][Postgres.shield]][Postgres-url]

* [![Vite][Vite.shield]][Vite-url]

(back to top)


## Getting Started

KoAkademy is a self-hosted academic management platform for student portals, admin work, enrollment, finance, schedules, and content.

Just want to run it? Start with Docker below. Want to contribute code? Jump to [Development](#development).

### Quick Start

This quick start uses the smallest practical setup: KoAkademy + SQLite + Redis.

- SQLite is the default database.

- Redis is included because the production image uses Horizon for queues.

One copy-paste quick start

```sh

mkdir -p koakademy && cd koakademy

mkdir -p database

touch database/database.sqlite

APP_KEY="base64:$(openssl rand -base64 32)"

cat > .env < compose.yaml <<'EOF'

services:

  app:

    image: docker.io/yukazakiri/koakademy:latest

    restart: unless-stopped

    env_file: .env

    ports:

      - "8000:8000"

    volumes:

      - koakademy-storage:/app/storage

      - ./database/database.sqlite:/app/database/database.sqlite

    depends_on:

      redis:

        condition: service_started

  redis:

    image: redis:7-alpine

    restart: unless-stopped

    volumes:

      - koakademy-redis:/data

volumes:

  koakademy-storage:

  koakademy-redis:

EOF

docker compose up -d

docker compose logs --tail=100 app

```

Open `http://localhost:8000`, then create your first admin user:

```sh

docker compose exec app php artisan make:filament-user

```

Image tags (which one should I use?)

* `docker.io/yukazakiri/koakademy:latest` — stable (recommended for most users).

* `docker.io/yukazakiri/koakademy:dev-latest` — rolling updates (for early testing).

* `ghcr.io/yukazakiri/koakademy:latest` — GitHub Container Registry mirror when enabled for a release.

To try the rolling build, change the app image to:

```yaml

image: docker.io/yukazakiri/koakademy:dev-latest

```

(back to top)


## Deployment

For self-hosting, start small with Docker Compose and add extra services only when you need them.

By default, the app already works with:

- SQLite database

- database-backed cache/sessions

- log mail driver

- collection search

Minimal Docker Compose (recommended starting point)

```yaml

services:

  app:

    image: docker.io/yukazakiri/koakademy:latest

    restart: unless-stopped

    env_file: .env

    ports:

      - "8000:8000"

    volumes:

      - koakademy-storage:/app/storage

      - ./database/database.sqlite:/app/database/database.sqlite

    depends_on:

      - redis

  redis:

    image: redis:7-alpine

    restart: unless-stopped

    volumes:

      - koakademy-redis:/data

volumes:

  koakademy-storage:

  koakademy-redis:

```

Required `.env` values for this minimal setup:

```env

APP_NAME="KoAkademy"

APP_ENV=production

APP_DEBUG=false

APP_URL=https://your-domain.example

APP_KEY=base64:replace-with-generated-key

PORTAL_HOST=your-domain.example

ADMIN_HOST=your-domain.example

REDIS_HOST=redis

QUEUE_CONNECTION=redis

```

Same thing with docker run

```sh

mkdir -p koakademy/database

touch koakademy/database/database.sqlite

docker network create koakademy 2>/dev/null || true

docker run -d --name koakademy-redis --restart unless-stopped --network koakademy redis:7-alpine

docker run -d \

  --name koakademy \

  --restart unless-stopped \

  --network koakademy \

  -p 8000:8000 \

  -v koakademy-storage:/app/storage \

  -v "$(pwd)/koakademy/database/database.sqlite:/app/database/database.sqlite" \

  -e APP_NAME="KoAkademy" \

  -e APP_ENV=production \

  -e APP_DEBUG=false \

  -e APP_URL=http://localhost:8000 \

  -e APP_KEY=base64:replace-with-generated-key \

  -e PORTAL_HOST=localhost \

  -e ADMIN_HOST=localhost \

  -e REDIS_HOST=koakademy-redis \

  -e QUEUE_CONNECTION=redis \

  docker.io/yukazakiri/koakademy:latest

```

Generate an app key with:

```sh

printf 'base64:%s\n' "$(openssl rand -base64 32)"

```

Production add-ons you’ll probably want later

* Put Caddy, Traefik, Nginx, Cloudflare Tunnel, or your platform proxy in front of port `8000` for HTTPS.

* Move to PostgreSQL when you need stronger multi-user production database operations (recommended).

* Add Meilisearch when you want external Scout search indexing.

* Configure SMTP for real outbound email.

* Use S3 or Cloudflare R2 for durable uploads if you run more than one app node or replace hosts often.

* Keep `/app/storage` persistent. For SQLite installs, also keep `/app/database/database.sqlite` persistent.

Database options (pick one)

### 1) SQLite (fastest way to get running)

```env

DB_CONNECTION=sqlite

```

Mount a writable file:

```yaml

volumes:

  - ./database/database.sqlite:/app/database/database.sqlite

```

### 2) PostgreSQL (recommended for production)

```env

DB_CONNECTION=pgsql

DB_HOST=pgsql

DB_PORT=5432

DB_DATABASE=koakademy

DB_USERNAME=koakademy

DB_PASSWORD=replace-with-strong-password

```

Example service:

```yaml

pgsql:

  image: postgres:17-alpine

  restart: unless-stopped

  environment:

    POSTGRES_DB: koakademy

    POSTGRES_USER: koakademy

    POSTGRES_PASSWORD: replace-with-strong-password

  volumes:

    - koakademy-pgsql:/var/lib/postgresql/data

```

### 3) MySQL / MariaDB (if that’s your existing stack)

```env

DB_CONNECTION=mysql

DB_HOST=mysql

DB_PORT=3306

DB_DATABASE=koakademy

DB_USERNAME=koakademy

DB_PASSWORD=replace-with-strong-password

```

Example service:

```yaml

mysql:

  image: mysql:8.4

  restart: unless-stopped

  environment:

    MYSQL_DATABASE: koakademy

    MYSQL_USER: koakademy

    MYSQL_PASSWORD: replace-with-strong-password

    MYSQL_ROOT_PASSWORD: replace-with-strong-root-password

  volumes:

    - koakademy-mysql:/var/lib/mysql

```

Environment notes

For the minimal Docker setup, these are the main values you should set:

* `APP_KEY` — required encryption key.

* `APP_NAME` — display name, defaults to `KoAkademy`.

* `APP_URL` — public URL used for generated links.

* `PORTAL_HOST` — portal route hostname. Use `localhost` for local testing.

* `ADMIN_HOST` — admin route hostname. Use `localhost` for local testing.

* `REDIS_HOST` and `QUEUE_CONNECTION=redis` — needed because Horizon runs in the production image.

The Docker image runs migrations by default (`RUN_MIGRATIONS=true`) and listens on port `8000`.

(back to top)


## Development

Working on KoAkademy locally? Use the setup scripts. They handle the boring setup for you: env file, dependencies, local domains, certs, and services.

Linux

```sh

git clone https://github.com/yukazakiri/koakademy.git

cd koakademy

./scripts/dev-setup.sh

```

Useful flags:

```sh

./scripts/dev-setup.sh --fresh

./scripts/dev-setup.sh --skip-ssl

./scripts/dev-setup.sh --skip-hosts

./scripts/dev-setup.sh --skip-docker

```

This script prepares the Docker Compose dev stack, local HTTPS certs, and hosts entries for `.test` domains.

If `portal.dccp.test` (or your portal host) shows `502 Bad Gateway`, see `docs/guide/getting-started/local-dev-troubleshooting.mdx`.

Windows / PowerShell + Laravel Herd

Install [Laravel Herd](https://herd.laravel.com/) first, then run:

```powershell

git clone https://github.com/yukazakiri/koakademy.git

cd koakademy

.\scripts\dev-setup.ps1

```

Useful flags:

```powershell

.\scripts\dev-setup.ps1 -SkipMigrations

.\scripts\dev-setup.ps1 -SkipNpm

.\scripts\dev-setup.ps1 -SkipHosts

```

The PowerShell script expects Laravel Herd and configures Herd-managed local domains and HTTPS.

Local development URLs

The scripts use domains from your `.env`. Common defaults are:

* `https://portal.koakademy.test`

* `https://admin.koakademy.test`

* `http://mailpit.local.test:8025`

Common development commands

```sh

php artisan migrate

php artisan test --compact

vendor/bin/pint --dirty --format agent

npm run dev

npm run build

```

If you are using Sail / Docker Compose for development, prefix PHP and Node commands with `vendor/bin/sail`.

(back to top)


## Usage

Quick links after the Docker quick start:

* `http://localhost:8000`

* `http://localhost:8000/admin`

* `http://localhost:8000/administrators`

Useful container commands:

```sh

docker compose up -d

docker compose logs --tail=100 app

docker compose exec app php artisan make:filament-user

docker compose exec app php artisan migrate --force

docker compose pull app && docker compose up -d

docker compose down

```

Local development commands:

```sh

php artisan migrate

php artisan test --compact

vendor/bin/pint --dirty --format agent

npm run dev

npm run build

```

Docs:

* [Getting Started](GETTING_STARTED.md)

* [Development Guide](DEVELOPMENT.md)

* [Deployment Guide](DEPLOYMENT.md)

* [Dev Container Setup](DEVCONTAINER_SETUP.md)

(back to top)


## Roadmap

- [ ] Continue migration of legacy hardcoded brand/domain strings to settings-driven values

- [ ] Expand API docs coverage for enrollment and finance endpoints

- [ ] Improve release automation and deployment validation checks

See the [open issues][issues-url] for a full list of proposed features (and known issues).

(back to top)


## Contributing

Contributions are welcome.

1. Fork the Project

2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)

3. Commit your Changes (`git commit -m 'feat: add amazing feature'`)

4. Push to the Branch (`git push origin feature/AmazingFeature`)

5. Open a Pull Request

Before opening a PR, please run:

```sh

vendor/bin/sail bin pint --dirty --format agent

vendor/bin/sail artisan test --compact

```

(back to top)


## License

Distributed under the GNU Affero General Public License v3.0 or later. See [`LICENSE.md`](LICENSE.md) for more information.

(back to top)


## Acknowledgments

* [Laravel](https://laravel.com)

* [Filament](https://filamentphp.com)

* [Inertia.js](https://inertiajs.com)

* [React](https://react.dev)

* [Tailwind CSS](https://tailwindcss.com)

* [Shields.io](https://shields.io)

(back to top)


[contributors-shield]: https://img.shields.io/github/contributors/yukazakiri/koakademy.svg?style=for-the-badge

[contributors-url]: https://github.com/yukazakiri/koakademy/graphs/contributors

[forks-shield]: https://img.shields.io/github/forks/yukazakiri/koakademy.svg?style=for-the-badge

[forks-url]: https://github.com/yukazakiri/koakademy/network/members

[stars-shield]: https://img.shields.io/github/stars/yukazakiri/koakademy.svg?style=for-the-badge

[stars-url]: https://github.com/yukazakiri/koakademy/stargazers

[issues-shield]: https://img.shields.io/github/issues/yukazakiri/koakademy.svg?style=for-the-badge

[issues-url]: https://github.com/yukazakiri/koakademy/issues

[license-shield]: https://img.shields.io/github/license/yukazakiri/koakademy.svg?style=for-the-badge

[license-url]: https://github.com/yukazakiri/koakademy/blob/master/LICENSE.md

[product-screenshot]: /public/images/image.png

[Laravel.com]: https://img.shields.io/badge/Laravel-FF2D20?style=for-the-badge&logo=laravel&logoColor=white

[Laravel-url]: https://laravel.com

[Inertia.shield]: https://img.shields.io/badge/Inertia-9553E9?style=for-the-badge&logo=inertia&logoColor=white

[Inertia-url]: https://inertiajs.com

[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB

[React-url]: https://react.dev

[Tailwind.shield]: https://img.shields.io/badge/Tailwind_CSS-38BDF8?style=for-the-badge&logo=tailwindcss&logoColor=white

[Tailwind-url]: https://tailwindcss.com

[Postgres.shield]: https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge&logo=postgresql&logoColor=white

[Postgres-url]: https://www.postgresql.org

[Vite.shield]: https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white

[Vite-url]: https://vitejs.dev