One-click installers for Exponential #

This page is for hosting companies that want customers to get an Exponential site with one click in their panel or order form. It answers: what Exponential already provides for unattended installs, which front end to build on, and what your one click must do around it.

Contents #

1. One installer, three front ends
2. Which front end for which offer
3. What the one click must do
4. Safety rules
5. What the customer receives

One installer, three front ends #

Every install method runs the same sequence of step classes in kernel/setup/steps/, from Welcome to Final; CreateSites is the step that writes the database, the packages and the settings. The front ends differ only in where the answers come from (4.1):

Source: 4.2.

Which front end for which offer #

What the one click must do #

Exponential installs the site. Your installer does everything around it:

1. Prepare the account: a system user, a home directory, a PHP-FPM pool or a Velocity instance for the site (Per-customer users and pools).

2. Prepare the database: nothing for SQLite 3 (the default; a writable var/storage/sqlite3/ is enough); for a server engine, an empty database and a user that may create tables (Databases and users in panels).

3. Put the code in place: a Git checkout of a release tag, or composer create-project/composer install from a lock file you tested (Composer and Git on servers).

4. Run the installer as the site's user, never as root:

   sudo -u <site user> env EXP_INSTALL_DB_PASSWORD='<from your secret store>' \
     php bin/php/console exp:install --dry-run --db=pgsql --db-user=<db user> --url=https://www.example.com
   sudo -u <site user> env EXP_INSTALL_DB_PASSWORD='<from your secret store>' \
     php bin/php/console exp:install --apply --db=pgsql --db-user=<db user> --url=https://www.example.com \
     --email=<customer contact>

5. Serve the site: point the web server at it, or start Velocity (Choosing a web server).

6. Install the crontab for runcronjobs.php (Cron jobs).

7. Hand over the password: read var/log/initial-admin-password once, give it to the customer through a secure channel, and delete the file; or set the password from your secret store with --password=.

8. Register the site in backups and monitoring.

Each step is described in Automating provisioning.

Safety rules #

• Never point --db-action=remove at a database that holds data. It is the default of exp:install and "empties the database first" (7.3). A one-click installer should create a new, empty database each time.
• Keep secrets off the command line. Use EXP_INSTALL_DB_PASSWORD rather than --db-password; an option "is visible to every user of the machine in the process list (ps) while the installation runs".
• Run as the site's user. "Files created by root cannot be changed by the web server later".
• Check the exit status. 0 installed, 1 anything failed; on failure maintenance mode stays on, and var/log/setup.log says why (7.7).
• Do not leave install files behind. A kickstart.ini holds passwords in clear text; remove it after the install, as the wizard would read it on a later run.

What the customer receives #

• The site address and the administration address (by URL /admin, by host, or by port, depending on --access).
• The administrator login admin and its password, once; advice to change it and create personal accounts (First sign-in and default passwords).
• The site package you chose, with or without demo content (Site packages).
• A link to the help: the help dashboard in their administration.

Related pages #

• exp:install
• The kickstarter
• Licensing for hosts (images and installers you distribute)
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.