Installation

KoAkademy runs as a self-managed Linux service with flexible deployment targets.

Deployment Options Matrix

Choose the self-hosting method that best aligns with your infrastructure:

Platform / Method	Recommended Use Case	Reverse Proxy / SSL	Multi-Node / HA	Guide
Linux VPS (1-Line Installer)	Dedicated VPS / Bare Metal	Built-in Caddy (Auto HTTPS)	Single-node Swarm	Quickstart
Docker Compose	Custom proxy / existing Docker host	Caddy / Nginx / Traefik	Single host	Compose Guide
Dokploy	Self-hosted PaaS / Single-pane UI	Traefik (Automated)	Project-based	Dokploy Guide
Coolify	Self-hosted PaaS / Multi-server UI	Traefik (Automated)	Multi-server	Coolify Guide
Docker Swarm	Lightweight container clustering	Caddy / Swarm Ingress	Native Multi-node	Swarm Guide
Kubernetes (K8s / K3s)	Enterprise / Cloud orchestration	Ingress / cert-manager	Native Multi-node	K8s Guide
Red Hat OpenShift	Enterprise OCP / OKD / ROSA	OpenShift Route (TLS)	Native Multi-node	OpenShift Guide

KoAkademy is beta software. Use staging first, review release notes, and keep a tested recovery path for institutional data.

Prerequisites

• A Linux VPS with root access
• A public domain with its DNS pointing to the VPS
• Free ports 80 and 443 for Caddy
• At least 4 GB RAM for a small evaluation
• Outbound access to GitHub, GHCR, Docker Hub, and any external providers

Docker does not need to be preinstalled. The installer uses Docker’s official installer when the engine is absent. It supports Docker’s Linux distributions and AMD64 or ARM64 hosts.

Quickstart (One-line Installer)

The fastest and officially supported production path is the automated one-line installer:

curl -sSL https://koakademy.koamishin.com/install.sh | bash

For non-interactive automation (e.g. cloud-init or CI), pass the target domain directly:

curl -sSL https://koakademy.koamishin.com/install.sh \
  | env KOAKADEMY_DOMAIN=school.example.com bash

What install.sh Does Under the Hood

The installer bootstrap executes with zero unnecessary assumptions and performs:

1. Host Verification: Validates a supported Linux host (amd64 / arm64). Installs Docker Engine automatically via Docker’s official script if missing.
2. Docker Swarm Setup: Initializes or preserves an active single-node Docker Swarm manager.
3. Secret Generation: Securely generates cryptographic Docker Secrets for APP_KEY, PostgreSQL credentials, and Redis passwords.
4. Private Overlay Network: Creates an isolated koakademy_private Swarm overlay network.
5. Caddy Edge Proxy: Starts Caddy on ports 80 and 443 with automatic TLS/HTTPS certificates.
6. Isolated Services: Spawns FrankenPHP (Laravel Octane on port 8000), PostgreSQL 18, Redis 8, and Gotenberg 8 (PDF rendering) on the private overlay network.
7. Database Migrations: Automatically runs database migrations before routing live traffic.
8. CLI Installation: Installs the koakademy management CLI to /usr/local/bin/koakademy (or /opt/koakademy/koakademy).
9. User Permissions: Configures the invoking user into the docker group for rootless Docker commands.

Once complete, open https://school.example.com/setup to finish the web setup wizard and register your school’s initial super administrator.

---

Operating KoAkademy via CLI

The installer provisions the koakademy CLI binary for day-two operations, updates, backups, rollbacks, and service configuration.

CLI Syntax & Command Overview

koakademy <command> [subcommand] [flags]

Core CLI Commands

1. Check System Status & Health

Inspect running containers, image versions, replica counts, and Swarm health:

koakademy status

2. Upgrades & Release Updates

Update to the latest stable release. This command automatically takes a PostgreSQL snapshot under /opt/koakademy/backups/, updates the immutable image digest, runs database migrations, and performs a zero-downtime rolling restart:

# Update to latest stable release
koakademy update

# Explicitly pin a specific release version
koakademy update --release v1.2.0

# Switch/Update to the edge channel (master branch)
koakademy update --edge

3. Image Rollback

If a newly deployed image experiences issues, rollback to the previous container image:

koakademy rollback

Database Migrations

koakademy rollback rolls back the application container image only. It never rolls back database schema migrations automatically. If schema changes are breaking, restore the database backup taken during the update step from /opt/koakademy/backups/.

4. Configure Object Storage (S3 / Cloudflare R2)

Configure durable object storage for uploads, institutional branding, and student documents:

# Cloudflare R2
koakademy configure storage r2

# Amazon S3 or S3-compatible storage (MinIO, Wasabi, DigitalOcean Spaces)
koakademy configure storage s3

# Digital Library private bucket
koakademy configure storage library-r2

# Revert to local container volume storage
koakademy configure storage local

5. Configure Transactional Email (SMTP / Sequenzy)

Set up outbound transactional notifications, email verification, and password resets:

# Configure SMTP
koakademy configure mail smtp

# Configure Sequenzy transactional provider
koakademy configure mail sequenzy

# Set mailer to local logs (development/testing)
koakademy configure mail log

6. Configure Search Engine (Meilisearch)

Enable or disable Laravel Scout full-text search indexing:

# Enable and connect external Meilisearch instance
koakademy configure search enable

# Disable Scout search (fallback to database search)
koakademy configure search disable

---

Inspect before running

Running remote privileged code is a trust decision. Download the matching stable release asset to inspect it:

curl -fSLO https://github.com/yukazakiri/koakademy/releases/latest/download/install.sh
less install.sh
env KOAKADEMY_DOMAIN=school.example bash install.sh

Each stable release contains the bootstrap, operator command, Swarm bundle, runtime configuration, image metadata, and SHA256SUMS. The installer verifies the release assets before changing the host.

Existing Swarm installation

The new installer deliberately refuses a host that still has legacy koakademy-* services. It makes no changes and points to the legacy Swarm migration guide. Back up PostgreSQL and storage, migrate during a maintenance window, and do not run the two topologies against the same data volumes.

Manual Docker Compose installation

Compose remains supported for operators who manage their own reverse proxy and environment file:

git clone https://github.com/yukazakiri/koakademy.git
cd koakademy
git checkout <latest-stable-tag>
cp .env.production.example .env
chmod 600 .env
docker compose --env-file .env -f compose.production.yaml config --quiet
docker compose --env-file .env -f compose.production.yaml up -d postgres redis gotenberg
docker compose --env-file .env -f compose.production.yaml run --rm app php artisan migrate --force
docker compose --env-file .env -f compose.production.yaml up -d app

Configure HTTPS in front of the Compose loopback port and complete /setup. Review Configuration and Deployment before accepting traffic.