The kickstarter for hosts #

This page is for system administrators who install the same kind of Exponential site again and again: a host's standard templates, staging copies, training sites. It answers: how the kickstarter works, how to keep its configuration as a reviewed template, and how not to destroy a database with it. The reference is Chapter 6.

Contents #

1. What it is
2. The commands
3. DatabaseAction
4. Templates with placeholders
5. Logs
6. Clean up

What it is #

"The kickstarter (bin/php/kickstarter.php, console name exp:kickstarter) runs the step classes in one PHP process on the command line and reads every answer from kickstart.ini" (4.2). It is the method "to use when the same installation has to be made more than once, when the answers should be reviewed as a file before they are applied, or when the site package comes from a local package repository".

The commands #

php bin/php/console exp:kickstarter ini --yes          # write kickstart.ini from the built-in defaults
php bin/php/console exp:kickstarter run --list-steps   # show the steps, change nothing
php bin/php/console exp:kickstarter run --dry-run      # check, stop after SiteDetails
php bin/php/console exp:kickstarter run --apply --force        # install

• ini writes the file: interactively, with --yes (built-in defaults) or --defaults (the values of kickstart.ini-dist).
• run installs from it. --force "is required whenever the range of steps includes CreateSites".
• A call without a command "shows the help and exits with status 0, so a script that forgot the subcommand does not fail; check that your scripts name run" (6.2).

DatabaseAction #

"A value that is missing or misspelled behaves like ignore": write it explicitly. Back up any database a run might touch into a directory outside the installation root first.

Templates with placeholders #

The pattern from 6.11, for a host's standard sites:

1. Keep a template such as deploy/kickstart.ini.template under version control, with placeholders for the customer values and secrets.
2. Render it at provisioning time into the installation root with mode 0600.
3. Dry run, then install, and fail on a non-zero status:

#!/usr/bin/env bash
set -euo pipefail
cd /var/www/vhosts/<domain>/<installation>
umask 077
envsubst < deploy/kickstart.ini.template > kickstart.ini
php bin/php/console exp:kickstarter run --dry-run
php bin/php/console exp:kickstarter run --apply --force
rm -f kickstart.ini

exp:kickstarter ini --from-installed fills Database from an existing installation's settings, which helps when you build a template from a site you already run (6.2.1).

Logs #

"var/log/kickstart.log and var/log/setup.log are the artefacts to keep from a failed job."

Clean up #

• Remove kickstart.ini after the install: it "holds passwords in clear text" and the wizard would read it on a later run (4.6).
• Deliver and remove var/log/initial-admin-password if a password was generated.

A public demo. With EXP_DEMO_MODE=1 in the environment of exp:kickstarter run, a well-known or short [site_admin] Password (publish, publishing) is installed as given instead of being replaced; an empty one is still replaced. The run's child process inherits the variable. Demo mode for hosts.

Related pages #

• exp:install for hosts
• Automating provisioning
• One-click installers
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.