Installing your academy

This guide installs your own copy of the academy on your own hosting. It takes about 20 minutes the first time. If you would rather we did it for you, or you get stuck at any step, email support@omnitelecom.co.uk.

What you need

A web address for the academy, for example academy.yourschool.co.uk, pointing at your hosting, with HTTPS switched on. Your licence is tied to this address the first time the academy checks in.
PHP 8.3 or newer, with these extensions: pdo_mysql, mbstring, openssl, tokenizer, xml, ctype, json, bcmath, fileinfo, gd, intl, sodium and curl. The zip extension is recommended. The installer checks all of these for you.
An empty MySQL 8 or MariaDB 10.6+ database, and a database user with full rights on it.
A cron job that runs once a minute. Most hosting control panels have a "Cron jobs" page.
Your licence key, from your licence area at https://on.training/my-licence.

Any of these will do: shared hosting (cPanel, Plesk, 20i StackCP and similar), a VPS or dedicated server, or Docker. Pick the section that matches yours.

1. Download

Sign in at https://on.training/my-licence, press Download, and check the download is complete: the page shows the file's SHA-256 checksum.

The zip contains one folder, academy. Everything below calls that folder "the app folder".

2. Put the files on your server

The important rule: only the app's public folder may be reachable from the web. Everything else (including .env, which holds your database password) must sit outside the web root.

Shared hosting

In your control panel's File Manager, upload the zip to your home folder (the folder that contains public_html, not inside it) and extract it. You now have a folder called academy next to public_html.
Point the web address at the app's public folder. Most control panels let you set the document root of a domain or subdomain: set it to academy/public. This is the best option; skip step 3 if you can do it.
Only if your host will not let you change the document root:
- Copy everything inside academy/public into public_html (including the hidden .htaccess file).
- Edit public_html/index.php and change the three paths that start __DIR__.'/../ to __DIR__.'/../academy/ (the maintenance file, vendor/autoload.php and bootstrap/app.php).
- Edit public_html/install.php and change the line $base = realpath(__DIR__.'/..'); to $base = realpath(__DIR__.'/../academy');.
- The installer notices that the public files live in public_html and tells the academy, so its styles, scripts and uploaded files are served from there. When you update, see "Updating" for the one extra step this layout needs.
Make sure PHP 8.3 is selected for the site (usually a "PHP version" page).

VPS or dedicated server (nginx and PHP-FPM)

Extract the zip to, for example, /var/www/academy.
Let the web server write to the folders that need it, and nothing else. The rest of the app stays owned by you, so a bug can never rewrite the code:
```
cd /var/www/academy
chown -R www-data:www-data storage bootstrap/cache
touch .env && chown www-data:www-data .env && chmod 640 .env
```
The empty .env is where the installer writes your settings.

An nginx server block (add HTTPS with certbot or your usual method). Only index.php and, until you delete it, install.php are ever run as PHP; any other .php file under public is refused:

server {
    listen 80;
    server_name academy.yourschool.co.uk;
    root /var/www/academy/public;
    index index.php;
    client_max_body_size 64M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ ^/(index|install)\.php(/|$) {
        try_files $fastcgi_script_name =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ \.php$ {
        return 404;
    }
    location ~ /\.(?!well-known) {
        deny all;
    }
}

The installer cannot create the public/storage link as www-data. After installing, run once as yourself: php artisan storage:link.

Apache works too: point the virtual host's DocumentRoot at /var/www/academy/public with AllowOverride All (the .htaccess file is included).

Docker

A ready-made Docker setup is being prepared. Until then, use the VPS instructions inside your own PHP 8.3 container, or ask us for help.

3. Run the installer

Do this straight after uploading, so nobody else gets to it first.

Open https://<your web address>/install.php, on the academy's own web address (the licence is tied to it).
If anything is marked Missing, fix it in your hosting control panel and reload the page.
Setup code. The installer has written a file called install-code.txt into the app's storage folder. Open it in your hosting File Manager (or, on a VPS, run sudo cat storage/install-code.txt) and copy the code into the form. This proves it is you filling the form, not someone who found the page first.
Fill in the rest: academy name, licence key, database details, your name, email and password. Email sending is optional here; you can set it up later.
Press Install. The installer checks your licence with on.training, builds the database and creates your owner account. It takes up to a minute.

If the licence check fails you will see why: a key that was not recognised, a key already used by another web address, a licence that is cancelled or not renewed, or on.training not answering (wait a minute and try again). Nothing is built until the licence is accepted.

If the install stops part-way (for example your host cuts off a long request), you will be told. Usually you can just press Install again; if the message says the database is half built, empty it first (drop its tables in phpMyAdmin or your host's database tool).

When it finishes:

Delete public/install.php (or public_html/install.php). It has locked itself (storage/installed.lock), but there is no reason to keep it. The setup code file is removed automatically.
Sign in at https://<your web address>/login.

4. Add the cron job

Add one cron job that runs every minute:

* * * * * php /path/to/academy/artisan schedule:run >/dev/null 2>&1

Use your own path, and use the PHP 8.3 command your host gives you (for example /usr/bin/php8.3, or php83): on shared hosting the plain php command is often an older version, and then the cron job silently does nothing. This sends queued email (password resets, invitations, certificates), runs the daily licence check and does the other housekeeping. Without it, emails stay queued and are never sent.

On a VPS you can also run a permanent queue worker for faster email (php artisan queue:work, as a systemd service). It is optional; the cron job alone is enough.

5. Set up email

If you did not enter a mail server in the installer, go to Settings, Email and enter your SMTP details, then send yourself a test email. Until you do, emails are written to the log file instead of being sent.

Uploaded files

Uploaded images and files are served through public/storage, a link the installer creates. Some shared hosts do not allow links. If images you upload do not appear, ask your host to allow symbolic links, or run php artisan storage:link from their terminal, or contact us.

Your licence

The academy checks its licence with on.training once a day. It sends only your licence key, web address and software version.
If your licence is not renewed, your academy keeps working. Your courses, learners and records are untouched. You stop receiving updates and new add-ons, and admins see a banner reminding them to renew.
If the academy cannot reach on.training for 7 days in a row, it treats the licence as not renewed until the next successful check. Nothing stops working.
To move the academy to a new web address, contact us and we will move your licence.

Updating

When a new version is available, it appears in your licence area.

Back up your database and the app folder.
Download the new zip and extract it somewhere temporary.
Copy its contents over your app folder, except .env and the storage folder: never replace those (the zip does not contain a .env, but take care not to delete yours). Do not copy public/install.php.
Only if your public files live in public_html (step 3 of "Shared hosting"): also copy the new public folder's contents into public_html, except index.php and install.php (your index.php has your edited paths).
Run, from the app folder:
```
php artisan migrate --force
php artisan optimize:clear
```
No terminal on your hosting? Ask us; one-click updates are coming.

Backups

The academy does not make its own database backups on your hosting; use your host's backup tool. Back up two things regularly: the database (your host's backup tool or mysqldump) and the storage folder (uploaded files). Keep a copy of .env somewhere safe: it holds the key that encrypts some of your data, and a backup cannot be read without it.

Troubleshooting

A blank page or "500 Server Error": check storage/logs/ for today's log file. Most often it is a folder that is not writable (storage or bootstrap/cache) or the wrong PHP version.
"The app folder is inside a web folder": the academy folder is inside public_html (or htdocs, httpdocs, html, wwwroot), so the settings file could be downloaded through your main web address, even if the academy's own address points at academy/public. Move the academy folder next to public_html and follow "Put the files on your server". (On a few hosts every site shares one web folder; if you see this message with the folder in the right place, contact us.)
"The installer is not available": either the academy is installed (there is a storage/installed.lock), or there is already a .env whose database the installer cannot confirm is an unfinished install of the academy. If this is a failed first install, delete .env and reload.
"That database already holds...": the installer only installs into an empty database (or its own unfinished one). Use a new, empty database.
Emails not arriving: check the cron job is running, then the settings in Settings, Email, then your spam folder.
"This licence key is already used by another web address": your licence is tied to the address it was first installed on. Contact us to move it.

For anything else, email support@omnitelecom.co.uk with your web address and what you see.