4. Choosing an install method #

Exponential 6.0 can be installed in three ways that all end in the same kind of installation: the setup wizard in a browser, the kickstarter on the command line driven by a kickstart.ini file, and the one-command console install exp:install, which builds that file from options. Under all three runs one engine: the step classes in kernel/setup/steps/, in the order of the step table in kernel/setup/steps/ezstep_data.php, and a site package whose install scripts shape the new site. This chapter explains that common engine, compares the three methods, lists exactly what an installation writes to disk and to the database, and recommends a method for each situation, including unattended installs in CI pipelines and containers. If you already know which method you want, skip to its chapter; if you will install more than once, or automate the install, read 4.4 and 4.6 first, because they describe what a reinstall destroys.

Contents · Previous: 3. Getting the code · Next: 5. The setup wizard

4.1 One installer, three front ends #

Every install method runs the same sequence of steps. Each step is a class eZStep<Name> in kernel/setup/steps/ezstep_<file>.php, and the order is fixed by eZStepData::$StepTable:

CreateSites is marked count_step => false: it is never shown as a page and does not count in the wizard's progress bar. It is the only step that installs the database, the site package and the siteaccess settings; the steps before it collect and check answers (DatabaseInit opens the database to test it, which creates an empty SQLite file if none exists, and in the browser LanguageOptions writes the character set to settings/override/i18n.ini.append.php), and keep what they found in memory for the steps after them. That is why an install cannot be resumed half-way in a new process: the kickstarter refuses a --start-step that would need those results (chapter 6).

The three front ends differ only in where the answers come from and how the steps are driven:

                 browser forms             kickstart.ini               command-line options
                 (one page per step)       (one section per step)      (exp:install --db=... --url=...)
                        |                          |                                 |
                        |                          |                  bin/php/install.php writes a
                        |                          |                  temporary kickstart.ini
                        v                          v                                 v
   kernel/setup/ezsetup.php           expKickstarter (kernel/classes/expkickstarter.php)
   (module setup, view init)          runs the same step classes in one CLI process
                        \                          |                                 /
                         \_________________________|________________________________/
                                                   v
                       eZStep* classes in kernel/setup/steps/  ->  CreateSites
                                                   v
                         site package install scripts (eZSitePreInstall, eZSitePostInstall, ...)

Two consequences follow:

• A fix or default in a step applies everywhere. The SQLite file checks, the language validation and the generated administrator password behave the same in the browser and on the command line (with the differences this book points out where they exist).
• kickstart.ini is read by the browser wizard too. The constructor of every step (eZStepInstaller) reads kickstart.ini in the installation root. When the wizard finds a section for a step, it pre-fills that page, or skips it when the section says Continue=true. See chapter 5.

4.2 The three methods at a glance #

The setup wizard #

The wizard starts by itself. settings/site.ini ships with:

[SiteAccessSettings]
CheckValidity=true

While that is true, the kernel (ezpKernelWeb) sends every request to the module setup, view init, with the page layout [SetupSettings] PageLayout=setup_pagelayout.tpl and without a session or a database. CreateSites writes CheckValidity=false to settings/override/site.ini.append.php, and from the next request on the site is served. The wizard needs a working web server first (chapter 8), and it is the only method that shows each decision on a page with an explanation. It is described page by page in chapter 5.

The kickstarter #

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. It has two subcommands: ini writes the file (interactively, or from defaults with --yes or --defaults), and run installs from it. 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. It is described in chapter 6.

The console install #

exp:install (bin/php/install.php) is a front end to the kickstarter. It turns its options into a temporary kickstart.ini, runs expKickstarter in the same process, removes the temporary file and puts back any kickstart.ini that was there before. Every option has a default, so

php bin/php/console exp:install --apply

alone installs the sevenx_multisite site package on SQLite (var/storage/sqlite3/exponential.db) with the administrator admin and a generated password, shown once at the end. It is described in chapter 7.

4.3 Site packages: what is installed #

The steps install a site package: an Exponential package of type site (package.xml with <type value="site" />), plus the packages it requires. Packages live in the package repository below var/storage/packages/; the vendor directory is set by settings/package.ini [RepositorySettings] Vendor (7x), so an imported package lands in var/storage/packages/7x/<name>/.

The package index of this version, [RepositorySettings] RemotePackagesIndexURL (https://exponential.packages.exponential.earth/exponential/6.0/6.0.15, whose index.xml lists the packages), offers twelve site packages. The ones you are most likely to choose:

A _clean package installs the same structure without the demo articles and images: choose it for a real site you will fill yourself, and the full one to evaluate Exponential.

Where packages come from:

• The remote package index. SiteTypes downloads the index from [RepositorySettings] RemotePackagesIndexURL in settings/package.ini (when it is empty: RemotePackagesIndexURLBase plus x.y/x.y.z, such as 6.0/6.0.15; before 6.0.15 the word stable was appended, which the package server does not have), and offers the site packages listed there next to the ones already imported. A package that is listed remotely and not yet imported is downloaded and imported, followed by the packages it requires.
• The local repository. A package already imported under var/storage/packages/ is used as it is. When the index cannot be downloaded, SiteTypes looks for an index.xml in the system repository instead, which is how an offline installation works.
• An upload. The wizard's Site package page has an Upload package field for an .ezpkg file.

Package install scripts: the "multi-site installer" #

A site package can carry PHP install scripts as <settings-file> entries in its package.xml. CreateSites calls the functions they define, when they exist, at fixed points:

sevenx_multisite lists ini-site.php, ini-admin.php, ini-common.php, sevenx-multi-site-installer.php, install-scripts.php, roles.php and preferences.php. Its install-scripts.php defines eZSitePreInstall() and eZSitePostInstall(), each of which creates a sevenxMultiSiteInstaller (a subclass of the kernel's eZSiteInstaller in kernel/classes/ezsiteinstaller.php) and calls preInstall() or postInstall(). This "multi-site installer" is therefore not a fourth install method: it is the site package's part of every install, whichever front end started it. If its post-install stops part-way, CreateSites reports error EZSW-080 ("The post-install of site package '...' stopped at step N of M (...): the steps after it did not run").

Other installer scripts you may meet #

4.4 What an installation writes #

All three methods end in CreateSites, so they write the same things. Knowing them makes it clear what a reinstall replaces and what has to be backed up.

Settings #

The siteaccess directory names are always site, admin and editor, plus adminui when the exp_adminui extension is in the installation. What you choose in the wizard, in kickstart.ini or with exp:install --site-access= is the match value: the URL path, the port or the host name that leads to each siteaccess. Access=www in URL mode therefore means "the path /www serves the siteaccess site", not a siteaccess called www.

The database password ends up in settings/siteaccess/site/site.ini.append.php and settings/siteaccess/admin/site.ini.append.php (and the editor and adminui copies), and an SMTP password in settings/override/site.ini.append.php. Keep settings/override/ and settings/siteaccess/ out of version control and readable only by the web server user; chapter 13 covers this.

Database #

What happens to the database is decided by the database action: the DatabaseAction key in kickstart.ini, --db-action for exp:install, or the Action drop-down the wizard shows when the database already holds tables.

The schema load creates every table the kernel declares, then imports each datatype's own .dba data (on engines other than SQLite) and, where the database supports it, the full-text part of the audit index. After that the site package and its required packages are installed into the database. The database engines themselves are the subject of chapter 9.

Files and logs #

Maintenance mode during the install #

Every method switches maintenance mode on while it works, so that no visitor meets a half-built database: var/maintenance.json exists, and the front controllers (index.php, index_rest.php, index_treemenu.php) answer every request with share/maintenance.html (or the active theme's errors/maintenance.html), HTTP 503 and a Retry-After header, before the settings or the database are touched.

• The kickstarter (and so exp:install) switches it on when the run begins and off when the installation is done. After a failed step it stays on: the run says so, and php bin/php/maintenance.php off ends it.
• The wizard switches it on at its first request, for every browser but its own (the cookie exp_setup_wizard), and off on its Finished page; a wizard that is left releases the site after 30 minutes (chapter 5).
• A dry run does not switch it on.

4.5 Which method for which situation #

Decision guide #

1. Do you have shell access? No: use the wizard. Yes: go on.
2. Must a person review every answer before anything happens? Yes: write kickstart.ini with exp:kickstarter ini, review it, then exp:kickstarter run --dry-run and run --apply.
3. Is the install part of a script, a pipeline or a container start-up? Yes: use exp:install with explicit options, the password in EXP_INSTALL_DB_PASSWORD, and check the exit status.
4. Otherwise exp:install is the shortest path, and the wizard the most explained one.

4.6 Unattended installs: CI and containers #

The command-line methods were built for unattended use. These rules keep such installs safe and repeatable.

Prefer exp:install in automation. It needs no file, validates its options before anything is written, and returns a non-zero exit status on every failure (chapter 7). The kickstarter is just as scriptable when the configuration is better kept as a reviewed file.

Keep secrets out of the command line. exp:install reads the database password from the environment variable EXP_INSTALL_DB_PASSWORD when --db-password is not given; that keeps it out of the process list and the shell history. kickstart.ini holds passwords in clear text: create it with mode 0600, never commit it, and remove it after the install (the wizard would read it on a later run).

Choose the administrator password deliberately. Without --password, exp:install generates a 24-character password and writes it to var/log/initial-admin-password (mode 0600). In a pipeline, either pass a password from your secret store with --password= (at least [UserSettings] MinPasswordLength, which is 10, and not a well-known one), or read the generated one from that file and rotate it.

Run as the web server's user. The installer creates files in settings/, var/ and design/. Run it as the user the web server or Velocity runs as, or fix the ownership afterwards; the system check tests the directory permissions as the user it runs as. Neither the kickstarter nor exp:install refuses to run as root (both accept --allow-root-user and ignore it), but files created by root may later be unwritable for the web server. Most other commands, exp:velocity among them, do refuse root unless --allow-root-user is given.

Make the database action explicit. Both exp:install (default) and the kickstarter files most people write use remove. That is what a fresh container wants, and exactly what must never point at a database that holds data you need.

Expect the run to be idempotent only with remove. Running the same configuration again with DatabaseAction=remove produces the same installation again. With ignore a second run adds a second copy of the data.

A minimal container entry point (installs once, then starts the server and stays in the foreground while it runs):

#!/usr/bin/env bash
set -euo pipefail
cd /srv/exponential
if ! grep -q '^\[DatabaseSettings\]' settings/override/site.ini.append.php 2>/dev/null; then
    php bin/php/console exp:install --apply \
        --db=mysql --db-host="${DB_HOST}" --db-name="${DB_NAME}" --db-user="${DB_USER}" \
        --url="${SITE_URL}" --email="${ADMIN_EMAIL}" --password="${ADMIN_PASSWORD}"
fi
php bin/php/console exp:velocity start
# exp:velocity start runs the server in the background and returns; status exits 0 while it runs
while php bin/php/console exp:velocity status >/dev/null 2>&1; do sleep 30; done
echo "Velocity stopped" >&2
exit 1

The test grep -q '^\[DatabaseSettings\]' settings/override/site.ini.append.php is the same test exp:install itself uses to decide that a directory already holds an installation. Pass EXP_INSTALL_DB_PASSWORD in the container's environment. The loop at the end matters: exp:velocity start detaches the server and returns as soon as it answers, so an entry point that ended with it would end the container's main process, and with it the container. The loop keeps the entry point alive while exp:velocity status reports the server as running (exit status 0) and ends the container when it stops, so the container runtime can restart it. If the entry point runs as root, add --allow-root-user to the two exp:velocity commands. Starting and configuring Velocity is the subject of chapter 8.

A CI smoke test that installs on SQLite and fails the job on any error:

php bin/php/console exp:install --dry-run          # configuration and packages, nothing written
php bin/php/console exp:install --apply --force --title="CI build ${CI_PIPELINE_ID:-local}"
test -f settings/siteaccess/site/site.ini.append.php
tail -n 20 var/log/setup.log

4.7 Before you start, whatever the method #

• The code is in place and the dependencies are installed (chapter 3), and PHP 7.4 or later with the extensions of chapter 2 is available.
• For a database server: the database and its user exist, and the user may create tables (chapter 9). SQLite needs only a writable var/storage/sqlite3/.
• settings/, var/ and design/ are writable by the user the install runs as.
• For the wizard: the site is served (chapter 8); Exponential Velocity is the recommended engine for every stage.
• You have a backup of any database the install might touch.

Installing a public demo. Every method works for a public demo whose administrator password is published: run it with the environment variable EXP_DEMO_MODE=1 and give the published password; the installers then install it as given, also publish or publishing. For a demo rebuilt on a schedule, exp:install on SQLite is the usual choice (Recipe: run a public demo on LiteSpeed and Plesk, Demo mode).

References #

In this repository:

• Installing Exponential 6.0: the one-page installation guide this book expands
• Kickstarter CLI and Kickstarter: install a whole site from one file
• Installing Exponential in one command
• The setup wizard's new look, and the editor siteaccess
• Clean install defaults
• Maintenance mode
• Installer logs and seed data
• Package installer batching
• Multi-site INI overrides
• Exponential console
• Velocity engines
• Audit log (the event system.install.run records every installation)
• Getting started and Deploying
• Code: kernel/setup/steps/ezstep_data.php, kernel/setup/steps/ezstep_create_sites.php, kernel/classes/expkickstarter.php, bin/php/install.php, kernel/classes/expmaintenance.php, kernel/classes/ezsiteinstaller.php

External:

• Exponential on GitHub: https://github.com/se7enxweb/exponential
• Exponential Velocity: https://github.com/se7enxweb/exponential-velocity
• Composer: https://getcomposer.org/doc/
• PHP command line usage: https://www.php.net/manual/en/features.commandline.php
• PHP proc_open() (used by the kickstarter's run log): https://www.php.net/manual/en/function.proc-open.php
• Package index of this version: https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/index.xml

Contents · Previous: 3. Getting the code · Next: 5. The setup wizard