Lesson 6.2: Installing a multisite with exp:install
exp:install installs Exponential with one command and no file to write first. Every option has a default, so the
command alone installs the default site package on SQLite. In this lesson learners give it the options a multisite
needs, host names for the site, the administration and the Editor, check them before anything is written, and read
what the command reports.
Note
Run this lesson in a fresh code directory, never in the installation of modules 1 to 5 and never on a live site.
At a glance
| Course | Multisite and site packages |
| Module | Module 6: Installing sites with the kickstarter and exp:install |
| Duration | 55 minutes (15 presenting, 40 exercise; the install itself takes a few minutes) |
| Level | Intermediate |
| Audience | Administrators, developers and hosts |
| Prerequisites | Lesson 6.1; a fresh directory with the code (Train the trainer, Lesson 2.2) |
Learning objectives
After this lesson, learners can:
- install with
php bin/php/console exp:install --applyand the options for host matching; - check the configuration with
--printand the whole run with--dry-run; - read the summary, find the generated password and remove the password file after the first login;
- explain the guard against overwriting an installation,
--forceand--db-action.
Trainer's notes
How to present it
Source: 7. The console install: exp:install.
- What it does (4 minutes). It checks every option before anything is written, chooses the administrator
password, builds the eleven sections of a
kickstart.ini, puts it in place (an existing one is moved aside), runs the kickstarter, saves the configuration masked asvar/log/exp-install-<date>.ini, deletes the temporary file and prints a summary. - The multisite options (5 minutes).
--access=hostwith--hostand--admin-host(both required, and different); the Editor getsedit.<host without www.>unless--editor-hostsays otherwise.--urlis the address every siteaccess's links are built from: always set it.--packagechooses the site package (sevenx_multisiteby default;sevenx_multisite_cleanwithout demo content). - Checks before the run (3 minutes).
--printshows the configuration, passwords masked, and writes nothing;--dry-runchecks the database and fetches the packages into a temporary repository, then stops: "Dry-run completed: database and remote packages verified. Stopped after SiteDetails, nothing written." - The password and the guard (3 minutes). Without
--password, a 24-character password is generated, shown in the summary and written tovar/log/initial-admin-password(mode 0600). Over an existing installation the command refuses unless--force; the default--db-action=removethen empties the database. For database servers, pass the password inEXP_INSTALL_DB_PASSWORD, not as an option visible in the process list.
Common questions
Why --url on a laptop? Without it every address points to http://localhost, which is right only when the site
is opened on the same machine.
Does exp:install start a web server? No. The addresses in the summary work once something serves the
installation root, for example Velocity as in Train the trainer lesson 2.4.
Can it use MySQL or PostgreSQL? Yes: --db=mysql or --db=pgsql with --db-host, --db-name and --db-user;
the database must exist first. SQLite needs nothing.
What is the exit status good for? 0 means installed (or a passed dry run, --print, --help); 1 anything
else, so a script can test $?.
Pitfalls
- Running as root. Files created by root cannot be changed by the web server later. Run as the user that serves the site.
- A value with a space.
--db mysqlis refused: every value needs=. - Short options.
-fis refused; the command knows long options only. - Losing the password. It is shown once. It is also in
var/log/initial-admin-passworduntil you delete it.
Hands-on exercise
In a fresh code directory, for example multisite-course, as the user that will serve the site.
Print the configuration for host matching:
php bin/php/console exp:install --print --access=host \ --host=www.club.localhost --admin-host=admin.club.localhost \ --url=http://www.club.localhost:8087 --title="Club" --email[email protected]In the output, find
Access,AccessHostname,AdminAccessHostname,EditorAccessHostname,Site_packageandDatabaseAction.Try a mistake: run the same command with
--admin-host=www.club.localhost. Read the message andecho $?.Run the same command as in step 1 with
--dry-runinstead of--print. Wait for the "Dry-run completed" line.Install: the same command without
--printor--dry-run. Note the time it takes.Read the summary: the site, the admin login, the editor address, the password and its note, the siteaccesses.
Run the install command of step 5 a second time and read the refusal. Nothing was touched.
Serve the directory on port 8087 as in Train the trainer lesson 2.4, then test the three hosts:
curl -sI -H 'Host: www.club.localhost' http://127.0.0.1:8087/ | head -1 curl -sI -H 'Host: admin.club.localhost' http://127.0.0.1:8087/ | head -1 curl -sI -H 'Host: edit.club.localhost' http://127.0.0.1:8087/ | head -1Read the host map the install wrote:
php bin/php/console exp:ini get 'site.ini/SiteAccessSettings/HostMatchMapItems[]'.Sign in to the administration (browser or
curl), change the administrator password, then deletevar/log/initial-admin-password.
Expected result
- Step 2:
Access=hostnamein[site_access], the three host names, the editor atedit.club.localhost,Site_package=sevenx_multisite. - Step 3 stops with "--host and --admin-host must differ" and exit status 1.
- Step 5 ends with the summary block "Exponential is installed".
- Step 7: "This directory already holds an installation ... Re-run with --force ..." and exit status 1.
- Step 8: the public host answers
200(or a redirect to the start page), the administration and the Editor answer with their sign-in pages or a redirect to them. - Step 9 lists the three hosts with
site,adminandeditor. - The trainer checks step 6 and step 8 on one learner's screen.
Quiz
- Which two options does
--access=hostrequire? - What does
--printdo that--dry-rundoes not, and the other way round? - Where is a generated administrator password written, and what do you do with the file?
- You run
exp:installagain in the same directory. What happens? A. It reinstalls B. It refuses without--forceC. It upgrades D. It asks a question - Why pass a database password in
EXP_INSTALL_DB_PASSWORD?
Answers
--hostand--admin-host, and they must differ.--printshows the configuration without touching the database or the network;--dry-runalso connects to the database and fetches the packages, then stops before anything is written (7.6).- In
var/log/initial-admin-password(mode 0600); change the password after the first login and delete the file. - B.
- An option is visible to every user of the machine in the process list and stays in the shell history.
Further reading
- 7. The console install: exp:install.
- Installing Exponential in one command.
- exp:install for hosts.
- 8. Serving the site and 10. After installing.
Related pages
- Module 6: Installing sites with the kickstarter and exp:install
- Multisite and site packages: course overview
- Trainers: start here
- 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.