Exponential / Download / Getting Started!
A step-by-step guide from your first look at Exponential to a site that is live and kept up to date: try the public demo, install your own copy, sign in, find your way around the administration, create content, add images, arrange pages with Exponential Layouts, translate, give people accounts, publish safely, go live and stay current. Every key action has a screenshot that shows where to click.
How to use this guide
This page follows the path most people take with Exponential. Read it from the top the first time, or jump to the stage you are at. Each stage is short: a sentence on why it matters, numbered steps, a screenshot of the key action with a caption that says what to click, and a few tips. Where a topic has more depth, a link leads to the full page of the free documentation on doc.exponential.earth.
You do not need to install anything for stages 1, 3 and 4: the public demo has everything. Stages 2, 11 and 12 are for the person who runs the server.
| Stage | What you do | Who it is for |
|---|---|---|
| 0. Before you begin | Learn the five words that everything else uses | Everyone |
| 1. Try the demo | Explore a complete installation in your browser | Everyone |
| 2. Install your own | Check the requirements, get the code, run the installer | Developers, hosts |
| 3. First sign-in | Sign in to the administration or the editor portal | Everyone |
| 4. The admin tour | The header, the columns, the dashboard and an item's page | Editors, administrators |
| 5. Create your first content | Create an article, fill in the form, publish | Editors |
| 6. Images and media | Upload files and use them in your content | Editors |
| 7. Layouts | Arrange pages with zones and blocks | Editors, site builders |
| 8. Translate | Publish the same item in more languages | Editors, translators |
| 9. Users and roles | Give each person their own account with the right permissions | Administrators |
| 10. Publish and versions | Drafts, versions, going back, hiding, the trash | Editors |
| 11. Go live | Serve the site, cronjobs, caches, backups, security | Administrators, hosts |
| 12. Keep it updated | Check, back up and update safely | Administrators, developers |
| 13. Common questions | Short answers, and a plan for your first week | Everyone |
| 14. Where to get help | The built-in help, the documentation, the community, and how to support the project | Everyone |
Short on time?
- Ten minutes: stage 1 (the demo), then stages 3 to 5 in the demo.
- One hour: add stage 2 on your own computer with SQLite and the built-in PHP server.
- A day: all stages, ending with the go-live checklist of stage 11.
- A week: follow the day-by-day plan at the end of stage 13.
Planning a site for a business or a club? Read Hosting your first Exponential website as well: it has the requirements table, the two ways to start (pre-installed hosting or install it yourself), five steps and a launch checklist.
0. Before you begin: five words to know
Exponential is a content management system: the software behind a website that lets people who are not programmers write, arrange and publish its pages. It is free software under the GNU GPL, version 2 or later, and it runs on PHP. A few words come back on every page of the administration and of this guide. Learn them once and everything else is easier.
| Word | What it means | Example |
|---|---|---|
| Content item (or object) | Everything on the site is a content item: a page, a news article, an image, a file, even a user account. | The article "Why track your workouts?" |
| Content class (or content type) | The kind of an item and the fields it has. An article has a title, an intro, a body and an image; a folder has a name and a description. | Article, Folder, Image, File, User |
| The content tree | Items are arranged in a tree, like folders on a computer. A folder holds articles, an article can hold images, and the address of a page follows its place in the tree. | Home > Fitness > Why track your workouts? |
| Draft, version, publish | A change is never visible at once. You work on a draft; the site shows it only when you publish it. The earlier version is kept, so you can always go back. | Version 3 is published, version 4 is your draft |
| Siteaccess | One installation answers in several ways. Each way is a siteaccess with its own address, design and settings. | site, admin, editor |
The three faces of one installation
A new installation always has three siteaccesses. What you choose during the install is only the address that leads to each one.
| Siteaccess | For whom | Typical address |
|---|---|---|
| site | Your visitors: the public website. | https://www.example.com/, or the path /site on a test machine |
| admin | Administrators: content, plus classes, roles, users, sections, setup, caches, updates and developer tools. | /admin, or a host of its own such as admin.example.com |
| editor | Editors: the administration for content only, without setup, design and developer tools. | /editor, or edit.example.com |
The admin and the editor portal look alike, because they are the same administration with a different set of tabs. Editors see what they need to write, translate, lay out pages and review; administrators see everything.
Who does what
| Person | Works in | Typical tasks | Read first |
|---|---|---|---|
| Editor | The editor portal | Writes, edits, translates and publishes content; uploads images; arranges pages | Stages 3 to 8 and 10 |
| Site builder | The administration | Plans the tree and the content classes, sets up layouts and their mappings | Stages 4 to 8 |
| Administrator | The administration and the server | Accounts and roles, caches, cronjobs, backups, updates | Stages 2, 3, 9, 11 and 12 |
| Developer | The code, with Git | Templates, extensions, integrations, fixes sent back to the project | Stage 2 (the GitHub way) and 12 |
On a small site one person often wears all four hats. That is fine: read the stages in order and you will meet each task when you need it.
Good to know
- Every person who works on the site gets their own account. The version history and the audit trail can then tell who did what.
- What you see in the administration depends on your role. If a tab or a button in this guide is missing for you, your role does not include it.
- Everything in this guide works in light and dark mode. The sun button in the header switches between them.
1. Try the demo: nothing to install
The fastest way to learn Exponential is to use it. A complete Exponential 6.0.15 installation is online for everyone: the public website, the editor portal and the administration. You can sign in, change anything you like and see how it works. Nothing you do there can harm anyone, because the demo is rebuilt every day.
The Demo section of the exponential.earth home page: the shared sign-in (admin and publish) and one button for each of the three addresses.
Open the demo
- Go to the Demo section of the home page. It lists the three addresses and the shared sign-in.
- Press Open the website to see the public site, demo.exponential.earth. It is the Fit & Healthy demo site, built with Exponential Layouts: articles, recipes and video pages, with search as you type.
- Look around as a visitor: open an article, use the search, switch the color mode. This is what your own visitors will see of a site built with Exponential.
The public demo website: the Fit & Healthy site, every page of it laid out with Exponential Layouts. On your first visit, answer the cookie notice with Reject all or Accept all.
Sign in to the administration
- Press Sign in to the administration on the home page, or open edit.demo.exponential.earth.
- Type admin under Username and publish under Password. This is the public demo login, published on purpose; it works on all three demo addresses.
- Press Sign in. The dashboard of the administration opens.
The sign-in page of the demo administration. Fill in Username and Password and press Sign in (outlined). The yellow Demo mode box says that this password is public.
Sign in to the editor portal
- Press Sign in as an editor, or open demo.exponential.earth/editor.
- Sign in with the same username and password.
- Compare the tabs with the administration: the editor portal keeps only what editors need, such as writing, translating, laying out pages, comparing versions and previewing at phone and tablet size.
The editor portal has its own sign-in page at /editor. The same demo login works here.
Five things to try in the demo
- Edit a page. Open Content structure, open an article, press Edit, change the title, press Send for publishing, then look at the article on the website (stage 5).
- Compare versions. On the same article press Manage versions and compare your version with the one before (stage 10).
- Rearrange a page. Open the Layouts tab, open a layout and drag a block to another zone (stage 7).
- Edit right on the website. Signed in, the website shows a slim tab at the side of its pages that opens a sidebar to edit the page you are on.
- Look behind the scenes. In the administration open Setup: caches, extensions, the audit trail and system information.
Good to know about the demo
- Everyone shares the same account, so you may see the changes of other visitors.
- The administrator password cannot be changed or reset there. Every page of the administration starts with a yellow Demo mode banner that says so.
- Every change is reset when the demo is rebuilt each day.
- Do not enter anything private: no real names, addresses or passwords.
- Want to know how the demo works? Read Demo mode.
2. Install your own copy
When the demo has convinced you, install Exponential on your own computer or server. A first test install needs only PHP and Composer: no database server (SQLite 3 is the default) and no web server (Exponential can start one for you). Plan about fifteen minutes the first time.
Prefer not to install anything yourself? Some hosts offer Exponential pre-installed; see Hosting your first Exponential website.
Step 1: Check the requirements
| You need | Minimum | Recommended |
|---|---|---|
| PHP | 8.0 (7.4 usable without support) | The newest 8.x your system offers; 8.5 is supported |
| PHP settings | memory_limit 64M, max_execution_time 30, date.timezone set, file_uploads on | More memory for sites with many images |
| PHP extensions | dom, libxml, mbstring, pcre, json, iconv, reflection, session, spl, simplexml, zlib, intl, xsl, one database extension, and gd or ImageMagick | Also curl, openssl and pcntl |
| Composer | 2.x | The current 2.x |
| Database | SQLite 3 (no server) | In the official order: SQLite 3, PostgreSQL, MongoDB, MariaDB, Oracle, MySQL |
| Web server | None: Exponential Velocity or PHP's own server | Velocity, or Apache or nginx with PHP-FPM |
| Git | Only for the GitHub way | Recommended for anyone who builds sites |
The quickest check of a machine is the installer itself: its system check runs every critical test and prints, for each failure, the cause and the fix. On a running installation, php bin/php/console exp:velocity ext check lists every PHP extension the installation wants and prints the install command for your system. The full list with the reason for each item is in chapter 2 of the installation book, Requirements.
Step 2: Choose how to get the code
| Way | Best for | What you get |
|---|---|---|
| From GitHub, with Composer | Anyone who builds websites | The kernel and every extension as Git clones with their full history: you see what changed, keep your own changes on a branch and send fixes back |
| With Composer only | A site you only run, or a quick test | One command fetches Exponential and everything it needs |
Both ways are on the home page, ready to copy: open the Install section and press Copy on the box you want.
The Install section of exponential.earth: From GitHub, with Composer on the left (recommended for building sites), With Composer only on the right. Press Copy to copy the commands.
Step 3: The quickest install, with Composer
Run these four commands in an empty folder. They download Exponential, install it on SQLite and start PHP's own server for a first look:
composer create-project se7enxweb/exponential exponential cd exponential php bin/php/console exp:install --apply --random-password --url=http://localhost:8087 php bin/php/console exp:velocity start --engine=php
- Open http://localhost:8087/site/ for the website.
- Open http://localhost:8087/admin/user/login for the administration.
- Sign in as admin. The password is printed once at the end of the install and written to var/log/initial-admin-password, readable by its owner only.
- Change that password after the first sign-in and delete the file (stage 3).
- Stop the server with php bin/php/console exp:velocity stop --engine=php.
Step 3, the other way: from GitHub
Building a website rather than trying one? Get the code as Git clones. First tell Composer, once per user account, to install every Exponential package as a Git clone; then clone the kernel, start a branch of your own and install:
composer config --global 'preferred-install.se7enxweb/*' source git clone https://github.com/se7enxweb/exponential.git cd exponential git switch -c my-site composer install php bin/php/console exp:install --apply
The clone holds the kernel with its whole history. Composer then clones every extension into extension/, each a Git repository of its own; the first install takes a few minutes. Updating later is two steps, always Git first and Composer second (stage 12). Step by step: Getting the code and Develop with Git.
Step 4: Pick an installer
One installer, three ways to drive it. They run the same checks and write the same installation.
| Installer | How | Use it when |
|---|---|---|
| exp:install | One console command with options | You want a working site in one step, as above |
| The setup wizard | In the browser, page by page | You prefer to see each choice, or have no shell |
| The kickstarter | Unattended, from a kickstart.ini file | Repeatable installs in CI, containers or for many sites |
Each has a chapter of its own: the console install, the setup wizard and the kickstarter. Not sure? Choosing an install method compares them.
Step 5: Serve it for real
PHP's own server is for development. For a real site, use one of these:
- Exponential Velocity, part of Exponential as of 6.0.15 and installed with it. It serves HTTP and HTTPS itself, with no separate web server. Start it with php bin/php/console exp:velocity start and see every address with php bin/php/console exp:velocity status.
- Apache or nginx with PHP-FPM, the classic setup. Put the rewrite rules into the virtual host itself rather than into .htaccess: .htaccess files are read on every request and slow every page down.
- FrankenPHP, LiteSpeed, Caddy and IIS are covered too.
Every setup, with ready configuration files: Serving the site.
What you just installed
Every command runs from the installation root: the directory that holds index.php, autoload.php, bin/ and settings/. A short map of what is in it:
| Directory or file | What it holds | Yours to change? |
|---|---|---|
| bin/php/console | The command console: exp:install, exp:velocity, exp:upgrade and many more | No, use it |
| design/ | The designs: standard and base as fallbacks, the administration designs, editor, and examples | No: put your own design in an extension |
| extension/ | Extensions: a few ship with the kernel, Composer adds the others | Yes, your own extensions |
| kernel/, lib/ | The kernel and its libraries | No: updates replace them |
| settings/ | The shipped .ini files; settings/siteaccess/ and settings/override/ hold your installation's own settings | Only siteaccess/ and override/ |
| var/ | Everything written at run time: caches, logs, uploaded files, and the SQLite database in var/storage/sqlite3/ | Back it up |
| update/ | Database update files per engine and version | No, apply them when you update |
| doc/ | The documentation, the same as on doc.exponential.earth | Read it offline |
| index.php | The front controller: every page request goes through it | No |
| runcronjobs.php | Runs the cronjob parts (stage 11) | No, schedule it |
Files that appear after an install and are yours alone, never to be committed or shared: settings/override/ and settings/siteaccess/ (they hold the database credentials), kickstart.ini, config.env.php and var/log/initial-admin-password.
Tips for the install
- Run Composer with the same PHP the site will use. The installer's PHP check exists to catch a web server PHP that is older than the command line PHP.
- When you run a script as root, add --allow-root-user; the script says when it is needed. Better: run everything as the user the site runs as.
- Many installations add a shortcut in the root (ln -s bin/php/console console), so ./console and php bin/php/console are the same program.
- Something failed? Troubleshooting lists the symptom, the cause and the fix for every stage of the install.
- Coming from an older system? Do not run the installer over an existing site. Start at the installation book, part V, migrating.
3. Your first sign-in
Everything you do with content starts with signing in to the administration or the editor portal. On your own installation the first account is admin, with the password the installer printed. On a site someone else runs, you get the address and a username from its administrator.
Find the address
| Form | Example |
|---|---|
| /admin after the site's address (the default of a new installation) | https://www.example.com/admin |
| /editor after the site's address | https://www.example.com/editor |
| A host name of its own | https://admin.example.com or https://edit.example.com |
Once signed in as an administrator, Setup > System information > Site addresses lists every address the installation answers to.
Sign in, step by step
- Open the address. The page says Sign in to Exponential, and the line under the title names the part of the installation you sign in to, such as Administration of Admin.
- Type your Username, or the e-mail address of your account: both work, because every account's e-mail address is unique.
- Type your Password. The eye button in the field shows what you typed.
- Leave Remember me ticked on your own computer, untick it on a shared one.
- Press Sign in (or Enter). The button says Signing in... while it works.
- If your account uses two-step sign-in, the next page, Confirm it is you, asks for the 6-digit code from your authenticator app or your e-mail. Type it and press Verify and sign in.
The administration opens on the Dashboard.
The dashboard right after signing in: the tabs in the header, the greeting with quick actions such as Content structure, Media library and Upload files, the counters, and your tools in the right column.
Right after the first sign-in on a new installation
- Open the user menu (the person button in the header) and choose Change password.
- Enter the Current password, then a New password twice. The page shows the rules, for example At least 10 characters, and checks them as you type. Generate a strong password makes one for you.
- Press Change password.
- On the server, delete var/log/initial-admin-password.
- Turn on two-step sign-in for your account (stage 9 shows the page). Administrators should always use it.
When signing in does not work
| What you see | What to do |
|---|---|
| The system could not log you in. | Check the username and the password; letters are case-sensitive. Too many wrong passwords lock an account for a while. |
| Access denied after a correct password | Your role may not sign in to this part of the installation. Editors usually sign in to the editor portal; ask an administrator. |
| A page Change password instead of the dashboard | An administrator asked you to replace a temporary password. Choose your own and continue. |
| You forgot the password | Choose Forgot your password? under the button, enter your e-mail address and follow the link in the e-mail. Check the spam folder if nothing arrives within a few minutes. |
| The lost password is the only administrator's | On the server, as root: php bin/php/resetuserpassword.php --allow-root-user -u admin -g generates a new one. |
| Too many wrong codes at the second step | The sign-in starts again with the password. Lost your phone? An administrator can switch your account to e-mail codes. |
Sign out
Use the last button at the right end of the header, an arrow leaving a box; pointing at it shows Logout and your username. While an item is open for editing the button is grayed out: finish or leave the edit first. On a shared computer, always sign out.
Tips
- Bookmark the sign-in page of each part you use; the admin and the editor portal have their own.
- Use a password you use nowhere else, and let a password manager remember it.
- Your devices and recent security events are one click away under Current user in the right column: Your devices and Security activity.
- Every step with every message you may meet: Logging into the admin, Logging into the Editor and Your account and signing in.
4. The admin tour: find your way around
Every page of the administration has the same frame: a header across the top, a left column for finding things, the page itself in the middle and a right column with your own tools. Learn the frame once and every page feels familiar. What you see depends on your role: an editor may see only Dashboard, Content structure and Media in the top menu, an administrator sees more.
The header, from left to right
| Part | What it does |
|---|---|
| Exponential logo | Back to the dashboard. |
| The tabs | Dashboard, Content structure, Media, Users, Layouts, Setup and more, depending on your role and the extensions of the site. Tabs that do not fit move under More. A small arrow next to a tab opens its menu of sub-pages. |
| Search... | Searches all content. The funnel button limits the search to a section or to the current place in the tree. Press / anywhere to jump to this field. |
| Globe button | Opens the public site, or another part of the installation, the way visitors see it. |
| Sun button | Color mode: light, dark or the mode of your computer. The choice is remembered for your account. |
| Person button | The user menu: your own user item, Change information, Change password, My e-mail preferences. |
| Arrow leaving a box | Logout. |
On a narrow screen, such as a phone, the tabs and the search move into a menu behind the button with three lines.
The editor portal: the same frame, fewer tabs
The editor portal is the administration for content only. It keeps Dashboard, Content structure, Media, Users (for members), Tags and the help, and leaves out setup, design and developer tools. Editors who only write and publish work here; the content is the same.
The dashboard of the editor portal. Compare the tabs with the administration above: no Setup, and quick actions only for content, media, uploads, users, tags and help.
The left column
- In Content structure and Media it holds the tree. Click the small triangle to open a folder, click a name to open the item.
- Click the icon in front of a name to open the item's menu: edit, copy, move, remove, create here, add to bookmarks and more.
- Trash is at the bottom of the tree.
- Below the tree, the Content finder opens an item from its number (ID), its path or its address on the site: type it and press Find.
- On the dashboard the column lists your own pages: My pending items, My drafts, My bookmarks, My e-mail preferences, My notification settings and more.
- In Setup it lists the pages of the setup in groups, each shown only to roles that may open it.
Content structure: the tree in the left column (click a triangle to open a folder, a name to open the item) and the top folder of the site with its sub items in the middle.
The right column
- Clear cache: for administrators. Editors usually do not need it.
- Bookmarks: your bookmarked items, and Bookmark this page for the one you are looking at.
- Interface: the Interface language of the administration and, where allowed, the Administration design.
- Current user: your name, with links to change your information and your password.
- User preferences and Quick settings: switches that change how pages are shown to you.
The tabs with a small arrow at the left and right edges of the window hide or show the columns. Drag the handle with three dots to make the left column wider; the administration remembers your choice.
The dashboard
- A greeting and quick actions: buttons to the places you need most, such as Content structure, Media library and Upload files.
- Numbers: content items, items published in the last seven days, My drafts, My pending items, and more for administrators. Click a number to open its list.
- Publishing, last 14 days: a small chart. Show the numbers shows it as a table.
- Lists: My pending items, My drafts, All latest content and My latest content.
- For administrators: blocks about the system, updates and security events, and the migrations.
An item's page
Open any item and its page shows, from the top:
- the path to it (click a part to go up), its name, its type (such as Folder or Article) and whether it is visible on the site;
- the buttons: a language list, Edit, Upload, Move, Copy, Remove, and three round buttons: View on site, Preview and Manage versions;
- a line with when it was changed, by whom, its version and its numbers (Node, Object);
- tabs with more about the item: View, Details, Translations, Locations, Relations and others;
- Sub items: the items below it, with buttons to create, select, sort and act on several at once.
The tabs of an item's page tell you everything about it without opening the edit form:
| Tab | What it shows |
|---|---|
| View | The item's content, field by field |
| Details | Creator, creation date, section, versions, translations and the node and object numbers |
| Translations | The languages the item exists in, and the missing ones (stage 8) |
| Locations | Every place in the tree where the item appears |
| Relations | The items it uses, and the items that use it |
The Tabs switch turns the tabs into one long page and back.
The page of a folder with its buttons outlined: Edit, Upload, Import/Export, Move, Copy and Remove. A button you may not use is grayed out; pointing at it says why.
Search: the fastest way to any item
- Click the Search... field in the header, or press / anywhere on the page (Ctrl + / or Cmd + / works even from inside another field).
- Type a word. From the third character on, suggestions open under the field in groups: Content, Users, Content classes and Administration (pages of the administration's menus, such as Setup > Cache management).
- Use the arrow keys and Enter to open a suggestion, or press Enter to see all results with their place in the tree and their type.
- Too many results? The funnel button, Search scope, limits the search to one section or to the place you are looking at, and leads to the search page with its filters.
You only ever see what you may open. Tick results and press Edit selected to edit several of them in one form.
Keyboard shortcuts worth learning
| Key | Where | What it does |
|---|---|---|
| / | Everywhere | Jumps to the Search... field |
| Esc | Menus and pop-ups | Closes the open menu, list or pop-up |
| Tab, then Enter | First press on a page | Skip to main content, past the header and the left column |
| Arrow keys | The content tree | Up and down move between items; right opens a folder, left closes it or goes to the parent |
| Letters | The content tree | Jump to the next item whose name starts with what you type |
| Shift+F10 | The tree, or a row of Sub items | Opens the item's menu: edit, copy, move, create here ... |
Every shortcut, for the tree, the tabs, the lists and the edit form: Keyboard shortcuts.
Tips for finding your way
- Press / to search from anywhere. The search finds content by any word in it.
- Bookmark the folders you work in every day: Bookmark this page in the right column.
- Know an item's number? Type it into the Content finder below the tree.
- Pages of the administration explain themselves in a sentence under the title, and buttons explain themselves when you point at them.
- The whole tour, with two walk-throughs: A tour of the administration.
5. Create your first content
This is the heart of Exponential: create an item, fill in its fields, publish it. Every content type works the same way; only the fields differ. The walk-through below creates an article in a folder. Try it in the demo first if you like.
Pick the right content type
Each content class is made for one job. Choosing the right one keeps the site consistent and makes items easy to list, search and reuse. A new installation comes with ready classes such as these:
| Class | Use it for | Main fields |
|---|---|---|
| Folder | A section of the site that holds other items, such as About or News | Name, Short name, Summary, Description, Display sub items |
| Article | A page of text: news, a blog post, a how-to | Title, Short title, Intro, Body, Image |
| Image | A picture, to use in articles, galleries and layouts | Name, Caption, Image with its alternative text |
| User | A person's account (stage 9) | First name, Last name, User account |
The site package you install brings more, such as a file to download or a product for the shop, and the classes of your installation may differ: the Create new list shows those you may use in each place. A site builder can add classes of its own (stage 13).
Create a new item
- Open the place where the new item belongs, for example a folder. Use the tree in the left column, or search for it.
- Under Sub items, press Create new. A list of the content types you may create here opens, in groups.
- Choose the type, for example Article. The edit form opens with an empty draft.
Under Sub items of a folder, press Create new and pick a content type from the list. The list only shows the types that may be created in this place.
Two other ways to the same result:
- The menu of an item in the tree (click the icon in front of its name) has Create here, with the same list.
- Create multiple new opens one form in which you fill in several new items below the same place at once.
Fill in the edit form
The edit form of an article. At the top the buttons Send for publishing, Store draft and exit and Discard draft; below them the field bar with one button per field; then one card per field.
The form is the same for every type. From the top:
- The buttons: Send for publishing, Store draft and exit, Discard draft.
- The title line names the item, its type and the language you are editing, for example English (American).
- The field bar: one button per field (Title, Short title, Intro ...); a click jumps to that field. A red * marks a required field: the draft cannot be published while it is empty.
- The fields, each with its type in the corner (Text, Rich text, Relation ...).
- The left column shows the item's numbers and dates, the draft you are working on, Manage versions and Preview.
- Type a Title. It becomes the item's name in the tree and, on most sites, part of its address.
- Write a short Intro: one or two sentences that lists and search results show.
- Write the Body in the rich text editor (below).
- Add an image with the image field (stage 6).
- Press Send for publishing.
Write rich text
Rich text fields such as Intro and Body have an editor with a toolbar: paragraph styles, bold, italic, lists, links, tables, special characters, Embed object (an image or another item inside the text), Fullscreen and Source code. Under the field you can switch between the editors your site offers, for example TinyMCE 8 and Tiptap; switching keeps what you typed.
The Body field with the rich text toolbar above the text and the editor switch (TinyMCE 8 or Tiptap) below it.
- Use the paragraph style list for headings instead of making text big and bold: headings give the page a structure that readers, search engines and screen readers understand.
- To link to another page of your own site, use the link button and pick the item, so the link keeps working when the page moves.
- The Help button of TinyMCE lists its keyboard shortcuts.
Publish, keep a draft, or throw it away
The three buttons at the top of every edit form: Send for publishing puts the change on the site, Store draft and exit keeps it for later, Discard draft throws it away.
| Button | What happens |
|---|---|
| Send for publishing | The draft becomes the published version and is on the site. If your site uses an approval, it waits under My pending items until someone approves it. |
| Store draft and exit | The draft is kept, only you see it, and it waits under My drafts on the dashboard. |
| Discard draft | After you confirm, the draft is thrown away. For a new item, the item is not created at all; for an existing one, the published version stays exactly as it was. |
The form saves the draft by itself every few minutes, so a closed browser tab costs little. Pressing Enter in a one-line field is the same as pressing Send for publishing.
Preview before you publish
Preview in the form's left column shows the draft as the site will show it. Buttons at the top of the preview show it at the width of a phone, a tablet, a desktop or a large desktop; Back to edit returns to the form, and Publish publishes from there.
Change an existing item
- Open the item.
- If it exists in more than one language, choose the language in the list next to Edit first.
- Press Edit. The form opens with a new draft, a copy of the published version. The site keeps showing the published version until you publish.
- Change what you need and press Send for publishing.
Someone else already has a draft of the item? The page Possible edit conflict appears first and lists the drafts with their creator and time. Continue one of your own drafts, start a New draft from the published version, or Cancel. Another person's draft cannot be edited: talk to them.
Move, copy, remove, and many items at once
- Move places the item somewhere else: choose the new parent in the browser that opens.
- Copy makes a copy in a place you choose. Copy subtree in the tree menu copies the item with everything below it.
- Remove moves the item to the trash after a confirmation (stage 10).
- In a Sub items list, tick several items and open More actions: Edit selected, Remove selected, Move selected, Copy selected, Hide selected, Unhide selected, and Add a location, which shows the items in another place too without copying them.
- Table options chooses the columns of the list, how many rows a page shows, and exports the visible columns as a CSV file.
Tips for your first content
- Plan the tree before you fill it: a folder per section of the site (for example Home, About, Services, Contact) keeps both the menu and the addresses tidy.
- Write the intro for someone who reads nothing else; it shows in lists, search results and previews.
- If the site has the writing assistant switched on, each text field shows Exponential Intelligence with Write, Rewrite, Translate, Suggest and Improve. Its suggestions change nothing until you accept them and store the draft.
- The full form explained: Creating and editing content.
6. Images and media
Every file you upload becomes a content item of its own: an image becomes an Image item, most other files a File item. You can then use it in articles, galleries and pages like any other item, and find it again with the search.
The media library
The Media tab opens the media library, a part of the content tree kept for files. On most sites it has folders such as Images, Files and Multimedia. It works like Content structure: open folders in the tree on the left, open an item to see it, and use Edit, Move and Remove on it. Files do not have to live in the media library: you can upload into any folder that accepts them, for example next to the article that uses them.
The Media tab: the media library with its folders as sub items. Open a folder from the tree on the left or from the list.
Upload files, step by step
The upload page takes one file or hundreds, by button, by dragging, or by pasting an image. Open it from Upload files in the quick actions of the dashboard, from Upload on the page of a folder, or from Upload multiple files in the menu of an item in the tree.
- Check the target location. The path is shown with Uploads allowed when files can be uploaded there. Click one of the Quick locations, such as Media, Images or Files, or press Change location... to pick another place.
- Add files. Press Choose files... or Choose a folder..., drag files or whole folders onto the dashed area, or paste an image you copied. The page shows the largest file it accepts.
- Check the queue. Before anything is sent, every file is listed with its name, size, type, a preview of an image, the type of item it becomes and a title you can change. For an image, fill in the alternative text where the site asks for it.
- Press Upload all. Three files are sent at a time, each with a progress bar. Retry failed tries the failed ones again.
- Check the result. The Uploaded list shows what was made, with View and Edit for each item.
Step 1: the target location with the Uploads allowed badge, and the Quick locations to change it in one click.
Steps 2 to 4: the queue with two images and a PDF before anything is sent. Give each image a title and an alternative text, then press Upload all.
Upload options
- Keep as drafts: the new items are not published. They wait in My drafts until you edit and publish them, for example to add a description first.
- Import compressed zip file(s) contents: the files inside a ZIP file are uploaded one by one instead of the ZIP file itself.
- A file with the same name and size already in the location is marked: skip it, rename the new one, or upload it anyway.
Put an image into an article
There are three ways, for three different needs:
| Way | How | Use it when |
|---|---|---|
| An image relation field | In the edit form, press Add existing to pick an image that is already there, or Upload new to upload one from your computer and link it. | Several pages should show the same image item, so that a new version of it appears everywhere |
| An image field of its own | Choose an existing image below the upload copies an image's file into the field, or upload a file straight into it. | The item should hold its own copy of the picture |
| Inside the text | Embed object in the rich text toolbar places an image item inside the body text. | The picture belongs at a certain place in the text, like the screenshots on this page |
An image relation field in the edit form: Add existing objects picks an image that is already on the site, Upload a file uploads a new one and links it.
Reuse an image that is already on the site
When an item has an image field of its own, the field offers Choose an existing image below the upload:
- Press Browse for an image to open the content browser in the media library, pick the item and click Select; or type part of its name into Search images by name and press Search.
- Press Use this image on the one you want. An empty search lists the newest images.
- Store the draft or publish it as usual to keep the change.
The image file is copied into the field, together with its alternative text when yours is empty. It is not a link: if someone later edits or removes the other item, your copy stays as it is. Want several pages to show the same image item? Use a relation field instead.
Tips for images and files
- Give each image an alternative text that says what it shows, for people who use a screen reader and for when the image cannot load. Some sites require it.
- Give files a clear title: it is what editors see in lists and searches, and often what visitors see as the link text.
- Keep the media library in folders, so you and others can find a file again.
- Remove files that are no longer used; they go to the trash first and can be restored.
- An upload fails with type not allowed or too big? Use another format or a smaller file, or ask an administrator. Every message explained: Images, media and uploads.
7. Arrange pages with Exponential Layouts
Content items hold the text; layouts decide how a page is arranged. A layout has a type (1 column, 2 columns, Sidebar left, Hero + 3 columns ...) that decides its zones (such as a header, the main area and a footer), and each zone holds blocks, one under the other: a title, a list of the newest articles, a gallery, a column, the full view of the item. You arrange them by dragging, in the browser, without touching a template. The whole public demo site is built this way.
The layouts dashboard
The Layouts tab opens the Layouts Dashboard: the numbers of layouts, zones, blocks and mappings, the recently changed layouts, and the buttons New layout, Layouts and Rules. Layouts lists every layout with its identifier, type, date and number of mappings, each with Open, Preview and Delete.
To start a new one, press New layout, choose a Layout type, give it a Name and press Create layout. The editor opens with the empty zones of that type.
Step 1: Open a layout
- Click the Layouts tab and open Layouts.
- Press Open on a layout. The editor opens on a draft of it: what you change stays in the draft, saved as you go, until you publish.
The layouts editor with a layout's zones HEADER, POST_HEADER, MAIN and PRE_FOOTER. Each zone shows its blocks with their type and a preview.
Step 2: Select a block and change its settings
- Click a block. It is outlined in blue.
- Its settings appear on the right in two tabs: Content (what it shows) and Design (how it looks).
- Change a setting. The block shows the change at once.
A selected Full view block, outlined in blue. Its Content and Design tabs are on the right.
Step 3: Add a block
- Press the plus button at the top left, Add a block.
- Find the block type in its group: Basic, Components, Listing, Gallery, Containers or Placeholders.
- Drag it into a zone. It is selected, ready for its settings.
A Title block dragged from Add a block into the empty POST_HEADER zone, selected and ready for its settings.
Step 4: Move, duplicate or delete
- Move a block by dragging its header bar to another place, in the same zone or another one.
- The menu with three dots on a block has Duplicate block and Delete block.
Step 5: Publish or keep the draft
| Button | What it does |
|---|---|
| Publish layout | The draft becomes the published layout; every page that uses it shows the change. |
| Publish and continue editing (menu with three dots) | Publishes and keeps the editor open. |
| Save draft and close (menu with three dots) | Keeps the draft for later; the site keeps the published layout. |
| Discard | Throws the draft away after you confirm in the Discard changes dialog. |
Shared layouts and linked zones
A shared layout holds blocks that many pages use, such as the header and the footer. Instead of copying those blocks, a zone is linked to a zone of the shared layout and shows its blocks. A linked zone has a red dashed border and hatched blocks. Its blocks cannot be changed in the linking layout: change them by opening the shared layout itself, and every page that links to it follows.
Which pages use a layout
A layout's mappings decide which pages use it: for example the page Fit & Healthy or every recipe below it. The first enabled mapping by priority whose targets and conditions match a page wins. The list is under Rules on the layouts dashboard (Layout mappings in the menu). Changing mappings decides what whole parts of the site look like, so ask a site builder if you are not sure.
Layout mappings: each mapping names its targets (such as a subtree or a location) and conditions, and links them to a layout.
Tips for layouts
- Practice on a copy of a layout, so nothing on the site changes until you are sure.
- Put what every page shares into a shared layout once, and link to it, instead of copying the header and footer into every layout.
- An item's page in the administration has a Layouts tab: the layout the page resolves to, with Preview and Edit layout, and the mappings applied to it.
- Every part of the editor in depth: The layouts editor.
8. Translate your content
Exponential keeps every language of an item together: an article can exist in English and in German, and each is a translation of the same item, with the same place in the tree, the same images and its own text. There are two different kinds of language, and it helps to keep them apart:
- Content languages: the languages your items are written in, which visitors read.
- The interface language: the language of the administration's menus, buttons and messages. You choose it for yourself; it changes nothing in the content.
See which translations an item has
On an item's page, the line under the buttons shows a small badge per language of the site. A filled badge, such as EN, is a translation that exists; a dashed badge, such as DE, is one that does not exist yet. Point at a badge to read it, for example Translate into German. The Translations tab lists them in full.
The Translations tab of an article: the existing translations with their locale and the main language, and below them the missing ones.
Translate an item, step by step
- Open the item.
- Click the dashed badge of the language, or choose New translation in the language list next to Edit and press Edit.
- If the page asks, choose the language under New translation and, under Translate based on, the translation to start from (its text is copied into the form), or None for empty fields.
- Translate the fields. The form names the language it is editing next to the title.
- Press Send for publishing.
The language list next to Edit, outlined: choose the language to edit, or New translation, before pressing Edit.
Each translation is published on its own: publishing the German text does not change the English one. To change an existing translation, choose that language in the list next to Edit first.
The main language
One translation of each item is its main language, marked as such on its badge. It is the language the item was created in, and the one shown where a translation is missing, if the item is set to be always available. The main language cannot be removed; other translations can be removed from the Translations tab by roles with the permission.
Change the language of the administration
- In the right column, open the list Interface language in the Interface box. It shows the most used languages first, then every language from A to Z, each with how complete its translation is.
- Choose a language and press Apply. The page loads again in that language.
The menus, buttons and messages change, and so do the formats of dates, times and numbers. The content, other users and other parts of the installation do not. The help follows the interface language too.
Setup, Interface languages: every locale of the administration, what it shows and how complete its translation is.
Tips for translating
- Start a translation from the main language with Translate based on: its text is copied into the form, so you translate instead of typing everything again.
- If Exponential Intelligence is on, its Translate button suggests a translation per field; nothing changes until you accept it.
- Adding a new language to the site is a task for an administrator: Languages explains both kinds and links to the full guide.
9. Users and roles: give people access
An account gets the roles of the user group it is in, and a role is a set of policies, the single permissions. So where you create an account decides what the person may do. This stage is for administrators; it gives a new editor an account of their own, step by step.
Which account for whom
| Group (under Users) | For whom | What they get |
|---|---|---|
| Editors | People who write, edit and publish content | The Editor role (limited to the Content and Media trees), Member, Member management and Editor account requests |
| Administrator users | Only the system administrators, the developers and the owners of the site | The Administrator role: everything, including users, roles, settings and updates |
| Members | The site's front-end members | The roles of the Members group; editors manage these accounts |
Give editors an account in Editors, never in Administrator users, even when they ask for "full access". And give every person their own account: never share one between several people.
Create an editor account, step by step
- Sign in (the editor portal is recommended, because it is what the new editor will use) and click Users.
- In the left column, click Editors. The group opens with its accounts under Sub items.
- Press Create new and choose User.
The Editors user group with its accounts under Sub items. Press Create new and choose User.
Then fill in the account:
- Fill in First name and Last name.
- Under User account, enter the Username (it cannot be changed in the form later) and the person's own work Email.
- Enter a temporary password twice. It must meet the site's rules, such as at least 10 characters and not a well-known password.
- Leave Change password at next sign-in ticked: the person must replace the temporary password before they can do anything else.
- Press Send for publishing. The site asks Verify it's you: enter your own password and press Confirm.
The form of a new user: name, Username, Password and Confirm password, Email, and the ticked box Change password at next sign-in.
Check the account
- Click the new account in the Editors group and open its Roles tab. It shows the roles of the group.
- Sign out, then sign in once as the new user with the temporary password. The site shows Change password instead of the dashboard: that proves the account works. Do not change the password here; sign out again.
- Send the new editor the address and the username by e-mail, and the temporary password by a second channel, such as a phone call. Never put all three into one message.
The Roles tab of a new editor: Editor limited to the Content and Media subtrees, Member, Member management and Editor account requests.
Turn on two-step sign-in
With two-step sign-in, a password alone no longer opens an account: after the password, the sign-in asks for a 6-digit code from an app on the phone or from an e-mail. Ask every new user, and every administrator without exception, to turn it on:
- Open My account and press Turn on on the Two-step sign-in card.
- Under Second step at sign-in, choose Authenticator app (TOTP) (recommended) or E-mail one-time code.
- For the app: scan the QR code with the app, then type the code it shows into Enter the code the app shows.
- Press Save settings. It applies from the next sign-in.
Setting up two-step sign-in: choose Authenticator app (TOTP), E-mail one-time code or Off under Second step at sign-in.
When creating an account goes wrong
| What you see | What to do |
|---|---|
| The username already exists or A user with this email already exists | Each username and each e-mail address belongs to one account. Choose another username, or check whether the person has an account already, as a member for example. |
| An error under Password | The password does not meet the rules: too short, or a well-known password. Use a longer random one. |
| Verify it's you refuses your password | Enter your own password, not the new person's. |
| The new user goes straight to the dashboard | The box Change password at next sign-in was not ticked. Edit the account, tick it and publish. |
| The new user sees Access denied or misses a tab | The account is in the wrong group, or the group lacks a role. Check the Roles tab. |
Tips for accounts and roles
- Never make an editor an administrator to solve a missing permission: give their group the permission instead, under Users > Roles and policies.
- Keep the number of administrators small. Granting the Administrator role is recorded in the audit trail.
- When someone leaves, disable the account the same day. Disabling keeps the name in the history of everything the person did.
- An account holds personal data: store only what the work needs and keep temporary passwords out of e-mail.
- Every step with every message: Setting up accounts for editors and administrators. What editors may do: What the Editor role allows.
10. Publish safely: drafts, versions and the trash
Exponential is built so that a mistake is never final. Every save of an item is a version, the earlier versions are kept, and a removed item waits in the trash. Knowing these four states is all it takes to publish with confidence.
| State | What it means |
|---|---|
| Draft | Being written. Only its creator sees and edits it. |
| Pending | Sent for publishing, but a workflow holds it, usually an approval. |
| Published | The version the site shows. An item has one published version at a time. |
| Archived | An earlier published version, kept so you can go back to it. |
When a draft is published, the version that was published before becomes archived. A site keeps a limited number of versions per item; when the limit is reached, the oldest archived version is removed to make room.
Your own lists
- My drafts (on the dashboard) lists the drafts you started and have not published. Open one to continue it. Removing the draft of a new item also removes that new item, which was never published.
- My pending items lists the versions you sent for publishing that a workflow still holds and, if you approve content, the versions waiting for your approval.
Go back to an earlier version, step by step
- On the item's page press Manage versions, the round button with a clock.
- The versions page shows an overview (how many versions, published, archived and your drafts), a filter and the list.
- Use View on a version to see its content, or Compare two versions: choose an older and a newer version and a translation, then press Show differences. Changes are marked field by field.
- Under New draft from this version, in, choose the translation and press Make a new draft.
- Check the new draft and publish it as usual. The current version is not changed until you publish.
The versions of an article with the status of each, published, archived or draft, and per version View, Compare and Make a new draft.
Hide an item instead of removing it
A hidden item stays in the administration but is not shown on the site, and nor is anything below it. Use it for content that is not ready, or not needed for a while.
- In the tree, open the item's menu and choose Advanced > Hide / unhide.
- In a Sub items list, tick items and choose More actions > Hide selected or Unhide selected.
- The badge next to the type on the item's page shows its visibility.
Remove and restore
- Remove on an item's page asks for a confirmation and moves the item, with everything below it, to the trash. Items in the trash are not on the site.
- Open Trash at the bottom of the tree. It lists the removed items with who removed them, when and where they were; filters narrow the list.
- Press Restore to put an item back. If its original place still exists it goes back there; otherwise you choose a new place.
The top of the trash: how many items it holds, and the filters Trashed by, Type and Trashed from and to.
Remove selected in the trash deletes items for good, and Empty trash deletes everything in it. Neither can be undone. When an item has more than one location, removing one location keeps the item in its other places.
Tips for publishing
- Not sure? Store a draft and preview it. Nothing reaches the site before you press Send for publishing.
- Comparing two versions is the quickest way to answer "who changed this, and what was it before?"
- Prefer hiding to removing for content you may need again soon.
- Your role decides whether you may restore or delete from the trash.
- All details: Publishing, versions and the trash.
11. Go live
A site that works on your computer is not yet a site that is ready for the public. Before you point your domain at it, go through the steps below. They take an afternoon and save many evenings later. This stage is for the person who runs the server.
Step 1: Check the installation
- Open the site's address and check the front page.
- In the administration open Setup > System information. It names the version of Exponential, PHP, the database and the server, and runs health checks.
- On an error, read var/log/error.log.
Setup, System information: the versions of Exponential, PHP and the database, the server, and the health checks with what to do about each warning.
Step 2: Serve it properly, over HTTPS
- Use Exponential Velocity, or Apache or nginx with PHP-FPM; not PHP's own development server.
- Put the rewrite rules into the server configuration, not into .htaccess, and set AllowOverride None: .htaccess files are read on every request.
- HTTPS on every host name, with plain HTTP redirected. A free certificate is fine; watch its renewal.
- Keep the administration on a host of its own, restricted by network or by a second authentication.
- The files: one user (or one group) writes var/ and settings/; no world-writable files; never run the PHP workers as root.
Running Velocity in production
- Start it with php bin/php/console exp:velocity start. It writes its configuration, starts in the background and prints the status.
- Run php bin/php/console exp:velocity status: it lists every address to open, including the administration's sign-in, Setup > System information and Setup > Caches.
- With the shipped values the site answers only on the machine itself. Set the address, the ports for HTTP and HTTPS and the user the workers run as, so that visitors can reach it and the workers never run as root.
- Serve a certificate from a certificate authority rather than the self-signed stand-in, and plan its renewal.
- Install a boot service, so Velocity starts again after a reboot.
Velocity also keeps a response cache: it answers repeat requests for anonymous pages without PHP and without the database. Signed-in visitors are never served from it. After a template or stylesheet change, clear it with php bin/php/console exp:velocity cache clear --apply.
Step 3: Set up the cronjobs
Cronjobs publish scheduled content, send notifications and newsletters, and clean up. List the parts, then add two lines to the crontab of the site's user:
php runcronjobs.php --list */5 * * * * cd /path/to/installation && php runcronjobs.php --siteaccess=site frequent 17 * * * * cd /path/to/installation && php runcronjobs.php --siteaccess=site infrequent
Use your public siteaccess name. The same parts are in the administration under Setup > Cronjobs, and Velocity's scheduler can run them without the system cron.
Setup, Cronjobs: the cronjob parts of the installation, when each one last ran, and buttons to run or pause them.
Step 4: Know your caches
Exponential caches a lot, which is why it is fast. When something you changed does not show, clear the smallest cache that fixes it:
| You changed | Command |
|---|---|
| a setting (.ini) | php bin/php/ezcache.php --clear-tag=ini |
| a template (.tpl) | php bin/php/ezcache.php --clear-tag=template |
| content looks stale | php bin/php/ezcache.php --clear-tag=content |
| added a template or an extension | php bin/php/ezcache.php --clear-id=template-override |
| unsure | php bin/php/ezcache.php --clear-all |
With Velocity, exp:velocity deploy does autoloads, caches and reloads in the right order. Administrators can also clear caches from the Clear cache box in the right column, or from Setup > Caches.
Setup, Caches: clear all caches, only the content caches, or a selection, and see what each cache holds.
Step 5: Back up, and test a restore
Back up the database and var/storage, settings/override and settings/siteaccess, every day. A backup you have never restored is a hope, not a backup: restore it once on another machine.
Step 6: The go-live checklist
- The generated administrator password changed, and var/log/initial-admin-password deleted.
- A personal administrator account per person, with two-step sign-in on.
- Debug output off ([DebugSettings] DebugOutput=disabled) and PHP display_errors=Off.
- Demo mode off: EXP_DEMO_MODE set for no process of the site, and no Demo mode banner.
- config.php and settings/override/ kept out of version control and readable only by those who need them.
- HTTPS on every name; secure session cookies on an HTTPS-only site.
- Security headers present on pages.
- Mail works: password resets and notifications arrive.
- The audit log verified, and someone receives its alerts.
- An update routine: who watches releases, how updates are tested, who receives security mail.
Tips for going live
- The full list, with the reason and the check for each item: Security hardening for production.
- Cron, mail, caches, backups, logs and monitoring in depth: After installing: the operations handbook.
- A short launch checklist for a small business site: Hosting your first Exponential website.
12. Keep it updated
Updates bring fixes, security improvements and new features. Exponential makes them routine: the same seven steps every time, from the command line or from the administration, with a backup first and a check at the end.
Know which version you run
- Setup > System information in the administration names it.
- So does php bin/php/console --version, for example console (Exponential) 6.0.15stable.
- Read the release notes of every version you pass. Each names the database update, the scripts to run once and the changes of behavior to check.
The seven steps of every update
- Back up and start a maintenance window. Maintenance mode answers every visitor with a 503 page while you work: php bin/php/maintenance.php on --message="Back soon" --until=30m.
- See what is waiting. The upgrade check and the update dashboard list what is new.
- Update the kernel with Git, on your branch: fetch, then merge the release you move to.
- Update the extensions with Composer: composer update. Always Git first, then Composer.
- Check files and database, and apply the database update.
- Clear the caches and reload the code.
- Check the site and leave the window: php bin/php/maintenance.php off.
The update dashboard of the administration: the installed packages, the updates available and the package servers, each on a tab of its own.
The same steps in the administration
Prefer pages to a shell? Every step has a page under Setup (the Administrator role has them all):
| Step | Page | What you press |
|---|---|---|
| 1. Back up, maintenance | Setup > Backup, then Setup > Maintenance | Make a backup; then write a message for visitors, choose the expected duration and press Take the site offline |
| 2. See what is waiting | Setup > Git Manager | Fetch now: it shows the commits the update brings, and changes nothing |
| 3. Update the kernel | Setup > Git Manager | Under Local branch, choose your branch, tick Regenerate autoloads and press Checkout |
| 4. Update the extensions | Setup > Updates and packages | Preview (dry run) first; with updating switched on, Run it for real |
| 5. Check files and database | Setup > Upgrade check | Check file consistency and Check database consistency |
| 6. Clear the caches | Setup > Cache management | Clear all caches |
| 7. Check the site | Setup > Log files | Look for new errors, then switch maintenance off |
Updating through Updates and packages is switched off until an administrator switches it on, because Composer rewrites the files of every package it updates. Switch it off again afterwards. Git Manager follows branches; to move to a release tag, use the command line.
One command for the database and settings: exp:upgrade
Steps 5 and 6 are one command. exp:upgrade brings the database and the settings up to the code the installation runs: it shows first what it would change, makes a backup, applies the steps in order, records what it did and checks that the site still answers.
./console exp:upgrade:status ./console exp:upgrade ./console exp:upgrade --apply
- exp:upgrade:status shows what is done and what is pending, and changes nothing.
- exp:upgrade without --apply is a dry run: what every pending step would change.
- exp:upgrade --apply takes a backup, then runs every pending step, then deploys and checks.
Run them from the installation root as the user the web server runs as. Without --apply nothing is ever written.
The upgrade check
Setup > Upgrade check compares the installation with the release it runs. Check file consistency compares every file of the release with its checksum, and Check database consistency compares the tables, fields and indexes with the schema. Both only read. A file listed as Modified that you changed on purpose belongs in an extension or in settings/override/, where updates do not overwrite it.
Setup, Upgrade check: press Check file consistency and Check database consistency before and after an update. Both checks only read.
Tips for updating
- Try every update on a copy first: restore last night's backup on a staging machine, update there, then update the live site.
- Keep your own changes in extensions, on your own Git branch, or in settings/override/: then an update never overwrites them.
- Choose how closely you follow: from every change on the main line to only each release. Update with Git has both tracks, the command line and the administration, step by step.
- The short, complete procedure with the rollback: Updating Exponential 6.0. From an older line (4.x, 5.x): Upgrading.
13. Common questions from new users
Short answers to the questions people ask most in their first weeks, each with a pointer to the stage or the page that says more.
About Exponential
| Question | Short answer |
|---|---|
| Is Exponential free? | Yes. It is free software under the GNU GPL, version 2 or later: free to use, study, change and share, for any site. |
| Which PHP do I need? | PHP 8.0 to 8.5 is supported; use the newest your system offers. PHP 7.4 is usable without support, without Velocity and Exponential Layouts. |
| Do I need a database server? | No. SQLite 3 is the default and a full production database: the database is one file under var/storage/sqlite3/. PostgreSQL, MongoDB, MariaDB, Oracle and MySQL are supported too. |
| Do I need Apache or nginx? | No. Exponential Velocity, installed with Exponential 6.0.15, serves HTTP and HTTPS itself. Apache, nginx, LiteSpeed, Caddy, IIS and FrankenPHP work as well (stage 2). |
| Is there an API? | Yes: a REST content API with OAuth 2.0, GraphQL, and personal API keys for your own scripts. See Integrating with Exponential 6.0. |
| I run a site on an older version, or on eZ Publish, the earlier name of the software. Can I move it? | Yes. Never run the installer over an existing site: start at the migration hub, which has a guide per path, also from other systems. |
About editing
| Question | Short answer |
|---|---|
| Should I use the admin or the editor portal? | Editors who write and publish use the editor portal; it has exactly what they need. Administrators use the admin (stage 4). |
| I published, but I still see the old text. | Reload the page. If it stays old, an administrator clears the content cache: the Clear cache box in the right column, or php bin/php/ezcache.php --clear-tag=content (stage 11). |
| Can I undo a publish? | Yes. Manage versions, choose the earlier version, Make a new draft, and publish it (stage 10). |
| I removed an item by mistake. | Open Trash at the bottom of the tree and press Restore (stage 10). |
| Two of us opened the same item. | The second person sees Possible edit conflict and can make a new draft or cancel. A draft belongs to its creator only (stage 5). |
| Where did my unfinished work go? | To My drafts on the dashboard. The form also saves a draft every few minutes while you work. |
| Why is a button grayed out? | You may not use it here, or not now, for example while an item is open for editing. Point at it to read why. |
| Why do I not see the Setup tab? | Your role does not include it. Editors work on content; settings, roles and updates belong to administrators. |
| Can I publish at a later date? | Yes, where the site offers it: the website sidebar can publish now or at a date, and the cronjobs publish scheduled content when its time comes (stage 11). |
About building and running a site
| Question | Short answer |
|---|---|
| How do I add a new kind of content, such as an Event? | Administrators define content classes in the administration; each class lists its fields and their types, and editors then create items of it. See The content model and editing content. |
| How do I change how the site looks? | Arrange pages with Exponential Layouts (stage 7). For the design itself: find the template that wrote a page and override it in an extension, as Templates and design shows. |
| How do I give someone only some permissions? | Put their account in a group whose roles fit, or give the group a new role with just the policies they need. See Roles and policies. |
| The demo will not let me change the admin password. | That is demo mode: on a public demo the administrator password is published and cannot be changed or reset. Your own installation has no such limit. |
| I lost the only administrator password. | On the server, as root: php bin/php/resetuserpassword.php --allow-root-user -u admin -g (stage 3). |
| Where do I see what went wrong? | In var/log/error.log, and in the administration under Setup > Log files. An error page shows a reference such as ERR-0123456789 that leads to the exact moment in the logs. |
Your first week, day by day
| Day | Do this | Stages |
|---|---|---|
| 1 | Explore the demo: website, editor portal and administration. Edit an article, compare versions, move a block. | 1, 3, 4 |
| 2 | Install Exponential on your own computer with SQLite and the built-in PHP server. | 2 |
| 3 | Plan the tree of your site on paper, then create its folders and first articles. | 5 |
| 4 | Upload your images and files, and arrange the front page with layouts. | 6, 7 |
| 5 | Add your languages, create accounts for the people who will edit, and turn on two-step sign-in. | 8, 9 |
| 6 | Move to a real server: Velocity or a web server, HTTPS, cronjobs, backups. | 11 |
| 7 | Go through the go-live checklist, test a restore, and launch. Then plan your update routine. | 11, 12 |
14. Where to get help
You are not alone with Exponential. The help is built into the administration, the documentation is free to read, and the community answers questions.
Inside the administration
- The help center: open Help center from the dashboard. It lists every help page by audience and topic, and its search finds any page in a second. The help follows your interface language.
- The page itself: many pages explain themselves in a sentence or two under the title, and buttons explain themselves when you point at them.
- Something looks broken? When something goes wrong lists what to check before you ask.
The help center: search all help pages, or filter them by audience, such as editors, administrators, developers or designers.
When you see an error page
Some pages look like errors but only say that something is not allowed or not there:
| What the page says | What it means | What to do |
|---|---|---|
| The requested page could not be displayed. (1) | Your role may not open this page or do this action. | Ask your administrator for access, if you need it. |
| The requested page could not be displayed. (20) | The address is wrong, or that part is not installed on this site. | Check the address; go back and use the menus. |
| Something went wrong on our side, with a reference such as ERR-0123456789 | A real error. It has already been logged. | Note the reference, the time, the address and what you did, and pass them to your administrator. |
| The site is in maintenance | The site is being updated. | Wait a moment and try again. |
A screenshot helps, as long as it shows no passwords or other people's personal data.
The documentation
| Read this | When |
|---|---|
| Getting started | Your first ten minutes as an editor |
| A tour of the administration | Every part of the screen, with two walk-throughs |
| Installing and running Exponential 6.0: the book | From an empty server to production, chapter by chapter |
| Installing Exponential 6.0 | The short installation guide |
| Develop with Git | Growing from user to developer, and sending your improvements back |
| Hosting your first Exponential website | Planning and launching a small site |
The community
- Forums: sign up and post your question at Share Exponential. You will be warmly welcomed.
- Chat: get quick answers in the Exponential Telegram channel, free for everyone.
- Bugs: errors in the kernel, the administration, the bundled extensions or the documentation go to the Exponential issue tracker; the project, the website and everything that is not an error in the software go to the project and community tracker. The Report an error page of the help center prepares the issue for you, with a safe summary of the installation.
- Code: every part of Exponential is free software with its full history on GitHub. Fixes are welcome as pull requests.
Tips for asking well
- Name your version (Setup > System information) and your PHP and database.
- Copy the exact message, and the lines around it from var/log/error.log.
- Say what you already tried. Never post passwords or other private data.
Support the project
Exponential is free software under the GNU GPL, version 2 or later: free to use, free to study, free to change and share. It grows because people give back.
- Share what you learn: a forum answer, a fixed typo in the documentation or a write-up of your project helps the next person.
- Contribute: extensions, fixes and translations, as pull requests on GitHub.
- Sponsor the maintainers through GitHub Sponsors, or with a one-time donation.
- Get professional help: 7x, the maintainer of Exponential, offers hosting and development, design and support services.
- Tell others about Exponential, online and in person.
Welcome to Exponential. Enjoy your freedom, and enjoy publishing.



































