Getting started: install Exponential and have a working site in minutes #

This guide is for anyone who starts with Exponential: an editor who wants a site to try, a developer, an operator. You need no prior knowledge. At the end you have an installed site, you are logged in to the administration interface, you have published a first piece of content, and you have changed a template and seen the change on the site. Allow ten to fifteen minutes. The install itself takes about a minute on SQLite.

Every command is run from the root of the installation (the directory that holds console, index.php and settings/). Commands that start with ./console are the same programs as php bin/php/<name>.php.

1. What you need #

Check the PHP you will use:

php -v

Expected: a line beginning PHP 8..

2. Get the files #

Pick one path. All three give the same installation.

A. Git clones with history (recommended when you build a website): the kernel and every se7enxweb extension arrive as Git clones, so you can see what changed, follow development and send fixes back. Develop with Git explains why and how.

composer config --global 'preferred-install.se7enxweb/*' source
cd /var/www
git clone https://github.com/se7enxweb/exponential.git exponential
cd exponential
git switch -c my-site
composer install

B. Composer project (the quickest way to a site you only want to try or run):

cd /var/www
composer create-project se7enxweb/exponential exponential
cd exponential

C. Packages. Single add-ons (content, classes, templates, files) are .ezpkg archives that you install after the base installation with ezpm, see ezpm and package compare and import. The installer in step 3 itself installs a site package (default sevenx_multisite), so you need nothing else for a first site.

Check that the console runs:

./console --version

Expected: the first line reads console (Exponential) 6.0.15stable (or the version you installed), and the text ends with Written by the Exponential Foundation and 7x (se7enx.com). If you run as root, add --allow-root-user to the scripts that ask for it. The script's message says so.

3. Install #

3.1 The one command #

./console exp:install --apply --random-password --url=http://localhost:8087

This installs the multisite site package on SQLite, in eng-US, with the siteaccesses site (the public site) and admin told apart by the first part of the address. The administrator password is generated (24 characters) and shown once at the end, and also written to var/log/initial-admin-password; --random-password asks for that explicitly. A password of your own with --password=... is kept as given when it has at least 10 characters and is not a well-known one such as publish or admin; otherwise a generated one replaces it and the summary says so. The install refuses to run over an existing installation unless you add --force, and --help lists every option.

Expected, at the end (values differ):

================================================================
  Exponential is installed
================================================================
  Installed:     <date> (<seconds>s)
  Site:          http://localhost:8087/site/
  Admin login:   http://localhost:8087/admin/user/login
  Username:      admin
  Password:      <the generated password>
  ...
================================================================

Copy the Admin, Username and Password lines now. A copy of the configuration used, with passwords masked, is in var/log/; the progress of the installation is in var/log/setup.log (what the logs tell you).

3.2 Other databases #

EXP_INSTALL_DB_PASSWORD='YOUR_PASSWORD' ./console exp:install --apply --db=mysql --db-host=127.0.0.1 \
    --db-name=mysite --db-user=root --db-action=remove --random-password --url=http://localhost:8087

--db-action=remove empties the named database first, so use a database that holds nothing you need. The default ports and names of each engine are in Install in one command.

3.3 From a file (repeatable installs) #

For the same installation on several servers, write the answers once and run them:

php bin/php/console exp:kickstarter ini        # writes kickstart.ini after a few questions
php bin/php/console exp:kickstarter run --dry-run
php bin/php/console exp:kickstarter run --apply --force

--dry-run checks the answers and the packages and writes nothing. See Kickstarter and, for every key, Kickstarter CLI. Keep your kickstart.ini out of version control; it holds the database password.

3.4 The browser wizard #

Open the site address in a browser before any installation exists and the setup wizard starts. SQLite is listed first and the bundled site is preselected, so pressing Next on every step installs the default site. See the setup wizard and clean install defaults.

4. See the site #

You need a web server that answers on the address you gave. For a first look use the one Exponential ships:

./console exp:velocity start --engine=php
./console exp:velocity status --engine=php

The php engine is PHP's own server and listens on port 8087 by default (velocity.ini [PHPServerSettings] Port), which is why step 3 used --url=http://localhost:8087. Open http://localhost:8087/site/ in a browser: you see the front page of the installed site. Stop it again with ./console exp:velocity stop --engine=php.

If you ran step 3 with another --url, use the Site address that the installer printed.

For production use Apache with PHP-FPM, or Velocity's own qbix or frankenphp engines: Velocity engines. Apache needs the shipped rewrite rules as .htaccess: ./console exp:setup:htaccess --apply copies them, and ./console exp:setup:status shows where .htaccess and config.php stand (Setting up .htaccess and config.php from the console). If a page is an error, nothing is hidden by the cache yet; read var/log/error.log and see Repairing an installation.

5. First login #

1. Open the Admin login address from step 3, for example http://localhost:8087/admin/user/login.
2. User name admin, and the password the installer printed.
3. You land on the dashboard of the administration interface.
4. Use the Change password link of the admin's user menu and choose a password of your own. If the installer wrote var/log/initial-admin-password, delete that file afterwards.

The first thing to know about the menus: a person only sees the entries their roles allow. admin is in the Administrator role and sees everything.

6. First content #

1. In the admin, open the Content tab, Content structure.
2. Select the top node (the front page folder) and choose Create here with the class Article (or Folder), then Create.
3. Fill in the title and the text in the editor, then press Send for publishing.
4. Open http://localhost:8087/site/ (reload) and look for your item. Its own page address is shown in the admin under Locations.

Class names and fields depend on the site package you installed; the content model is explained in Content model and editing.

If an item is published but missing from a list, clear the content cache once:

php bin/php/ezcache.php --clear-tag=content --allow-root-user

The cache command and its groups: ./console exp:cache --help; a dry run of any clear is --dry-run.

7. First template change #

A template is a .tpl file. The site shows the design named by the public siteaccess; ask Exponential which one:

./console exp:ini where site/DesignSettings/SiteDesign site

Expected: the files that set it, in load order, and In effect: with the design name (for the multisite package the last line reads SiteDesign=media or similar; use the name you are shown).

Click path (safe, no files) #

1. Admin menu: Design > Template Editor.
2. Choose a template of your design, for example the one for the article full view, and open it.
3. Add a visible line, for example <p>Hello from my template</p>, and save.
4. Reload the item on the site: the line is there.

How the editor creates, orders and edits overrides: Template editor.

File path (what you put in version control) #

1. Find the template that renders what you want to change. Switch on the template path comments to see it in the page source: see Template path comments.
2. Copy the file from where it is (for example design/standard/templates/) to the same relative path under your design's directory design/<design>/templates/ (or its override/templates/), and edit the copy.
3. If you added a new template path rather than changing an existing file, clear the template caches once: php bin/php/ezcache.php --clear-all --allow-root-user.

The order in which designs and overrides are tried is in Template override ordering and Extension loading order.

8. When something goes wrong #

Related pages #