keel-laravel — Laravel PHP framework appliance
===============================================

A Keel Linux appliance for deploying Laravel applications. Built on
the LNMP layer, which carries nginx, MariaDB, and PHP-FPM. This layer
adds Composer, Node.js, npm, and the PHP extensions Laravel needs.

Parent layer: **lnmp**.

Build
-----

::

    bt-layer laravel --parent lnmp

What it ships
-------------

- Composer, Node.js, and npm for dependency management and frontend
  tooling (Vite).
- PHP extensions: xml, curl, zip, mbstring, cli.
- A route of keel-web's default site,
  ``/etc/nginx/keel-default.d/60-keel-laravel.conf``, that serves
  ``/var/www/laravel/public`` on 80 and 443. Only ``public/index.php`` runs.
  The check page of lnmp (``/keel-check/``, its hook and the database
  ``keel_check``) is removed: it is not part of a Laravel product.
- The Laravel application in ``/var/www/laravel``, from
  ``composer create-project laravel/laravel`` (major version 12) at build
  time, so a machine needs no network at its first boot. The image holds no
  ``.env`` and no ``APP_KEY``.
- The appliance manifest ``/usr/share/keel/appliances/laravel.yaml``.
- Webmin on 12321, web shell on 12320.

What it inherits
----------------

- nginx on 80/443 (from lnmp).
- MariaDB (from lnmp); the pair modes of the LNMP layer apply.
- PHP-FPM (from lnmp).

First boot
----------

``firstboot.d/45laravel`` reads the instance description and:

1. checks every value and stops with the name of a bad option;
2. makes the MariaDB database (``app.options.database``, default
   ``laravel``) and the account of the web user, ``www-data``, over the
   socket (``unix_socket``, no password), with its grant on that database;
3. stores the APP_KEY (``secrets.app_key``, the stored row, or a new key from
   ``php artisan key:generate --show``) as the row ``app_key`` of the table
   ``keel_settings``, and writes ``/var/www/laravel/.env`` (mode 0600, owned
   by www-data);
4. runs ``php artisan migrate --force`` and waits until the site answers.

On a cloud pair, keel seeds the database of the replica from the primary and
replicates it, so both nodes have one APP_KEY and one account: the provider
``KeelSharedKeyServiceProvider`` of the application reads the key from the
database before anything encrypts. A server that is read only (a replica)
gets no write; the hook takes the key that the primary stored.

Options: ``name``, ``environment`` (production, staging, local, testing),
``debug`` (refused in production), ``url``, ``database``. LNMP already uses the names ``db_password`` and
``db_user`` for its administrative account, so this layer does not. See
``keel/instance.example.yaml``.

Tests
-----

``tests/coverage.sh`` runs the bats suite under kcov; ``COVERAGE.md`` has
the measured numbers. ``tests/boot-test.sh`` boots the layer in LXC and
checks that the welcome page carries the name the first boot wrote.