The three installers, from a bundler's view
This page is for bundlers deciding how their bundle installs the site. Exponential has one installation sequence with three front ends. The reference is Chapter 4: Choosing an install method.
Contents
- One sequence, three front ends
- Side by side
- Which one your bundle calls
- What every installer writes
- Maintenance mode during the install
One sequence, 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" (One-click installers).
| Front end | Started by | Answers from |
|---|---|---|
| Setup wizard | opening the site in a browser while [SiteAccessSettings] CheckValidity=true | browser forms (pre-filled by kickstart.ini if present) |
| Kickstarter | php bin/php/console exp:kickstarter run --apply or php bin/php/kickstarter.php run --apply | kickstart.ini in the installation root |
| Console install | php bin/php/console exp:install --apply or php bin/php/install.php --apply | command-line options, each with a default |
Side by side
| Setup wizard | Kickstarter | exp:install | |
|---|---|---|---|
| Needs a web server during the install | yes | no | no |
| Dry run | no | run --dry-run | --dry-run, --print |
| Guard against overwriting | starts only while CheckValidity=true | --force required | refuses an existing installation without --force |
| Log | var/log/setup.log | setup.log, kickstart.log | setup.log, var/log/exp-install-<date>.ini |
| Administrator password | typed in the form | from the file; generated when empty or well known | generated unless an acceptable --password is given |
| Exit status for scripts | not applicable | 0 or 1 (6.2.3) | 0 or 1 (7.7) |
Source: 4.2 and the chapters linked.
Which one your bundle calls
| Bundle | Front end | Why |
|---|---|---|
| Container image, CI, automated environments | exp:install | "It needs no file, validates its options before anything is written, and returns a non-zero exit status on every failure" (4.6) |
| Panel installer | exp:install | options map to the panel's form fields |
| Agency starter kit, several reviewed environments | the kickstarter | "the reviewed kickstart.ini is the specification of the install" |
| Server image whose customer finishes the install | the setup wizard, pre-filled by kickstart.ini | the customer chooses the site details in a browser |
| Shared hosting without shell | the setup wizard | "it needs only a browser and FTP access" (4.5) |
Details: Unattended install with exp:install, The kickstarter for bundles.
What every installer writes
All three end in CreateSites, "so they write the same things"
(4.4):
| Where | What |
|---|---|
settings/override/site.ini.append.php | siteaccess matching, site list, mail settings, ActiveExtensions from the site package |
settings/siteaccess/site/, admin/, editor/ (and adminui/ when exp_adminui is present) | per-siteaccess settings, including the database password |
| the database | schema, base data, site package content |
var/storage/packages/, var/storage/sqlite3/ | imported packages, the SQLite file |
var/log/setup.log, var/log/initial-admin-password | the run's log; a generated password (mode 0600) |
"The siteaccess directory names are always site, admin and editor"; what you choose is the match value
(URL path, port or host). A bundle's documentation should say which addresses it configured.
Warning
Because the installers write secrets into settings/override/ and settings/siteaccess/, a bundle must never ship
those directories filled from its build machine. Install at the recipient's first start
(First boot and install once).
Maintenance mode during the install
"Every method switches maintenance mode on while it works": var/maintenance.json exists and the front
controllers answer HTTP 503. After a failed step it stays on; php bin/php/maintenance.php off ends it. "A dry run does
not switch it on" (4.4). A
bundle's health check should treat 503 during first boot as "installing", not as "broken".
Related pages
- One-click installers for Exponential
- Chapter 5: The setup wizard
- Install in one command
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.