# Open School by Enki Gold — install v0.1.0

This is the first self-hosted pilot. It contains four sample lessons for ages
8–11 and 12–14. All four age pathways are available when staff write lessons.
There is no external service, default account, open registration or required
learner email. This package is separate from the existing Enki Gold website.

## New installation

1. Create the subdomain `home-school.enkigold.com` in your host or aaPanel.
   If you own and intended to use `home-school.ankigold.com`, use that hostname
   instead. Point its DNS to the server and enable HTTPS.
2. Unzip and upload the **whole** `open-school/` directory. Set the subdomain's
   web document root (running directory) to **`open-school/public/`**. Keep the
   package itself outside any other site's web root. The `storage/`, `app/`,
   `bin/` and `migrations/` directories must never be public. PHP runs in
   `public/`, and `index.php` is the default document.
3. Use PHP 8.2 or newer, with sessions and **PDO SQLite** (SQLite 3.27 or newer
   for backups). Give the PHP site user private write access to `storage/` and
   configure a writable PHP session directory. Run the following in the project
   directory **as the same user that runs PHP for this site**. Do not set storage
   permissions to 777.

   ```sh
   php bin/school.php setup-key
   ```

4. Visit the subdomain or open `/install.php`. Paste the one-time key and choose
   the first super admin username and passphrase. The installer creates the
   database, adds the starter lessons, records the release, and closes setup.
5. Sign in. Use **Accounts** to create a staff, admin or student account. Share
   temporary passphrases privately. At first sign-in, each account holder
   chooses a new passphrase.

If the terminal and the website run different PHP installations, choose the
terminal binary that matches the site's PHP version and extensions. For
TLS termination at a trusted proxy, configure PHP's HTTPS flag in the web
server (or set the server-side environment variable `OPEN_SCHOOL_HTTPS=1` only
where direct public HTTP access is blocked).

## Who can do what

| Role | Access |
|---|---|
| Student | Browse published lessons, do practical tasks, take self-assessments and read their own feedback. |
| Staff | Write or edit their own drafts, preview assessments, submit drafts, and withdraw their own submissions. |
| Admin | Manage staff and student accounts. Review, publish, return or unpublish lessons. |
| Super admin | All admin functions, plus managing admin and super admin accounts and seeing releases, migrations and administrative activity. |

The learner age pathway is a recommendation. Students can explore other
pathways when lessons are available. An assessment result preserves the
questions, answers and feedback from that attempt even if the lesson changes.

## Backups and upgrades

- Check the installed release and migration status: `php bin/school.php status`
- Make a private database backup: `php bin/school.php backup`
- To upgrade, put the subdomain into host-level maintenance, take a copy of
  the current code and back up the database. Upload the new release's code
  and migrations, preserving the entire existing `storage/` directory.
  Run `php bin/school.php upgrade` as the site PHP user.
- The upgrader creates another database backup and applies pending migrations
  in a transaction. A successful upgrade appears under **Releases**. The app
  does not serve signed-in pages while the package and database versions differ.
- Confirm the version with `status`, then sign in and smoke-test the site
  before ending maintenance. Keep backups out of all public roots and store
  a protected copy away from the server.
- If a migration fails, review the CLI error; the database transaction rolls
  back. To restore after a committed upgrade, stop site traffic and restore
  the matching previous code and database backup together. Keep a copy of the
  current database before replacing it; restoring older data drops later changes.

When publishing future packages, bump the version in `release.json`, append a
new numbered migration when the schema changes, and leave previously shipped
migration files intact. Migrations are checked against their recorded checksums.

## Troubleshooting

- **Setup key not recognised:** generate a fresh key with the same site
  user, reload setup, and use the latest key.
- **Setup cannot write:** check the owner and permissions of `storage/`,
  and confirm the terminal and web PHP both have the SQLite driver.
- **503 after an update:** run `php bin/school.php status`. Upload the
  complete matching release and apply the upgrade.
- **Local evaluation:** run `php -S localhost:8080 -t public` in the project
  directory and use a setup key. Use the built-in server only for local testing.