[Enhancement] Increase Robustness and Usefulness of Web-Based Installer/Updater

[nagmat84]

Summary

For users who don't have CLI access to their web-space or who feel uncomfortable using a CLI, Lychee provides a web-based installer and updater. This aspect of Lychee is in need of some serious improvements:

1. Verbose error reporting and robust handling of errors
2. Add requirement checking before update (also see #1168)
3. Proper encoding of in- and outputs (also see #1248)
4. Reduction of duplicate logic in the backend
5. Finalize configuration, incl. creation of admin user

Details

Wrt. to Item 1

The installer basically consists of four (mostly static) HTML pages which are process one after another. The updater consists of two such pages. During the transition between two consecutive pages, the backend runs a one step of the installation/update procedure (e.g. pull the new commits, install composer dependencies, migrate the DB, etc.). If the steps works as excepted, fine, but if anything fails, the web-based installer does not handle any error messages properly. The user does not get any specific feedback about what went wrong, but usually only sees a generic "500 Server Error" page. Without detailed information, we (the developers) are also unable to help the user. Moreover, the user is very often trapped in a undefined state from which the web installer cannot recover.

Wrt. to item 2

At the moment, the updater only checks wether a newer version of Lychee is available and allows the user to download it, but the updater does not check, if the host meets all requirements of the update. This way the updater is actually able to make the Lychee installation unusable (for example, if the newer version uses language feature of PHP 8 and compulsory requires PHP 8, but the host only provides PHP 7). At the moment, only the installer checks requirements for a freshly unpacked Lychee installation.

Wrt. to item 3

Needless to say anything about that. As the installer/updater does not take care of proper input/output encoding, certain characters which are necessary for a proper configuration of the backend but also have a special meaning for HTML cannot be configured (see #1248). In theory, this could also enable chances for security issues.

Wrt. to item 4

The process of an initial installation and an upgrade of an existing installation have certain steps in common (e.g. requirement checking, migration of DB). Currently, the installer and the updater implemented as two completely different things which leads to duplicated code which unfortunately also differs slightly. For example,

• DB migration during installation is handled by
  • \App\Http\Controllers\Install\MigrationController::view() and
  • \App\Actions\Install\ApplyMigration::migrate(), while
• DB migration during upgrade is handled by
  • \App\Http\Controllers\Administration\UpdateController::force() and
  • \App\Actions\Update\Apply::artisan().

(Not to mention that the methods in the latter case a badly named.)

Wrt. to item 5

During installation there are indeed two configuration steps. An early configuration step even before a DB connection is configured and a final configuration step after the DB is fully functional. Today, this final configuration only creates the first admin user. At the moment this final configuration step is not considered part of the installation routine, but left to the login procedure of an operational Lychee instance. This has two major drawbacks:

• First of all, it is a security risk. If the admin password is not set as part of the installation, anybody can anonymously login to Lychee as soon as it becomes operational and set the admin password. Moreover, if the legitimate admin of Lychee resets the admin password, the entire gallery becomes accessible publicly until a new admin password is set.
• It complicates the code of the login procedure of the frontend.

[nagmat84]

These are my initial ideas.

I am planning a new state machine with the following states:

1. Callow
2. Scaffolded
3. Migrated
4. Installed

Theses states are commonly used for installation and update. In particular, after an update has been downloaded the same migration check is used as during installation.

The name of the states is still questionable. I had no better idea than callow and scaffolded but I am open for any improvement. @kamil4: You are living in the US, right? Maybe you could come up with some nice (and short) names?

The state Installed is a super-state and is partitioned into three sub-states (note the glasses symbol in the UML diagram). I am planning the following new sub-states:

1. Installed -- UpToDate
2. Installed -- UpdateAvailable
3. Installed -- UpdateApplicable

The transition event CheckForUpdate is called periodically using the same trigger as now (I believe during login). In state UpdateAvailable the user is only informed about the existence of a newer version, but some requirements are not met. In the state UpdateApplicable the user is also allowed to download the update.

@ildyria, @kamil4, @d7415: What do you think? Any feedback/ideas? Anything which I should keep in mind when I renew the installer/updater?

[ildyria]

That looks quite good to me, but in your first UML diagram, we are missing the dependency check and folder permission check that are also executed in the /install path. Those are really necessary in my opinion before doing anything. Or should I assume they are included in the Callow step ?

[nagmat84]

Or should I assume they are included in the Callow step?

Yes, or more precisely there is an invisible out and in-going edge (a loop) from/into the Callow state which is labeled Check.... I was simply too lazy to draw it.