Study guide · System Configuration and Caching
Configuring, maintaining and speeding up TYPO3
A TYPO3 installation has settings that apply to every page: database, sessions, image processing, error output. You learn where they live, who may change them and how to use different values per environment. After that, it is about the cache, and finally about the Admin Panel, which helps you investigate slow pages.
The example: the Lindenau music school
The integrator Mara is building the website of the Lindenau music school as a Composer project with TYPO3 14.3. There are three environments:
- On Mara's laptop, the project runs in DDEV at the address lindenau.ddev.site.
- A test server shows new features to the school's management before they go live.
- The live system runs at www.musikschule-lindenau.example.
On her laptop, Mara wants to see every error with all its details. Live, visitors should never see internal information. The home page should load fast and still show new concert dates right away.
Where TYPO3 stores its settings
All installation-wide settings end up in the global array TYPO3_CONF_VARS. It is split into sections: BE for the backend, FE for the frontend and SYS for general system values. There are also DB for the database, GFX for images and MAIL for sending email. Do not confuse it with the TCA array, which describes tables and fields.
The array is filled in three layers:
- The defaults live in
DefaultConfiguration.phpin the core extension. You never change this file. - The file
settings.phpin the folderconfig/systemcontains everything that differs from the defaults. - The file
additional.phpin the same folder is loaded afterwards and can override any value.
The settings.php is a machine-written file. TYPO3 rewrites it every time a system maintainer saves something in the Settings module under System. The Install Tool password is stored there too, as a hash under the key installToolPassword in the BE section. You may edit the file by hand. But the next time someone saves in the backend, TYPO3 generates it completely anew, and your comments are gone. Composer has nothing to do with this file.
You maintain the additional.php yourself. TYPO3 never overwrites it. It is a normal PHP file and may contain logic, such as a check of the application context. It is loaded on every request, so it should not contain expensive computations. A value from additional.php always wins, even if the backend shows a different value.
<?php
use TYPO3\CMS\Core\Core\Environment;
if (Environment::getContext()->isDevelopment()) {
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['host'] = 'db';
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['password'] = 'db';
} else {
$GLOBALS['TYPO3_CONF_VARS']['BE']['lockSSL'] = true;
}Other configuration lives elsewhere. The site configuration is stored in YAML files under config/sites, and the .htaccess file controls the web server. Since TYPO3 14.2, you can also read and set single values of settings.php on the command line, with configuration:show and configuration:set from the system extension lowlevel.
The application context
The application context tells TYPO3 which environment it runs in. There are three main contexts: Production, Development and Testing. In addition, there are sub-contexts, for example Production/Staging for Mara's test server. If nothing is set, Production applies.
You set the context with the environment variable TYPO3_CONTEXT. With Apache, you do this with SetEnv in the virtual host or in the .htaccess, and it can depend on the domain. Variables such as APP_ENV or NODE_ENV belong to other frameworks and mean nothing to TYPO3.
SetEnv TYPO3_CONTEXT Production/StagingTYPO3_CONTEXT=Development vendor/bin/typo3 cache:flushYou can see the current context in the backend in the System Information menu in the top bar, next to the TYPO3 version and the PHP version. That way you notice at once whether you are working on the live system.
You can react to the context in several places:
- In additional.php with a check, as in the example above.
- In TypoScript with the applicationContext condition. For sub-contexts, a comparison with matches and a regular expression works well.
- In stdWrap with getText, that is, data with the value applicationcontext.
- In the site configuration with
baseVariants. They hold other base addresses with a condition. If none matches, the normal base applies.
[applicationContext == "Development"]
page.10.value = Development system
[end]
[applicationContext matches "/^Production/"]
config.admPanel = 0
[end]
page.20 = TEXT
page.20.data = applicationcontextbase: 'https://www.musikschule-lindenau.example/'
baseVariants:
- base: 'https://lindenau.ddev.site/'
condition: 'applicationContext == "Development"'So Mara needs only one page tree and one site configuration for all environments.
System maintainers in the backend
The maintenance tools of TYPO3 are together called the System Maintainer Area, formerly the Install Tool. In the backend, they are the modules Maintenance, Settings, Upgrade and Environment under System. Only admins who are also system maintainers see these modules. Editors without admin rights are never system maintainers, no matter which group they belong to.
Who is a system maintainer is stored in the list systemMaintainers in the SYS section, as a list of user IDs. You maintain it in the Settings module with the card Manage System Maintainers. There is no dedicated user group for it. During setup, TYPO3 adds the first admin itself.
How strict TYPO3 is depends on the context:
- In the Development context, every admin counts as a system maintainer, even if the list is empty. No extra confirmation is needed.
- In Production, the list applies. Before opening the modules, TYPO3 asks for a renewed confirmation, the so-called sudo mode. You enter your backend password or the Install Tool password once more.
If nobody knows the Install Tool password any more, a system maintainer still reaches all maintenance functions through the modules under System. There they can also set a new Install Tool password.
The Install Tool without the backend
The Install Tool also exists as standalone access without a backend login. By default, you reach it at the path /typo3/install. Since TYPO3 14, it uses the backend routes and follows the backend entry point. If entryPoint in the BE section is set to admin, the Install Tool lives at /admin/install.
Because no backend account is needed, TYPO3 protects this access twice:
- A file called ENABLE_INSTALL_TOOL must exist. Whoever can create it has write access to the server.
- You need the Install Tool password. It is independent of all backend passwords.
Where does the file go? In a Composer installation, TYPO3 checks two places: the folder var/transient and the folder config. In a Classic installation without Composer, they are typo3temp/var/transient and typo3conf. In the web root public or under vendor, the file is ignored. Other flag files have other jobs: FIRST_INSTALL starts the first installation, and LOCK_BACKEND locks the backend.
The file expires. It is valid for 60 minutes, and each use of the Install Tool extends this time. Once it has expired, TYPO3 deletes it on the next access, and the Install Tool is locked again. It also disappears when you log out. If the file contains the text KEEP_FILE, however, it stays. Then you must delete it by hand, otherwise the Install Tool stays open, protected only by the password. The status report warns about this.
touch var/transient/ENABLE_INSTALL_TOOL
echo KEEP_FILE > var/transient/ENABLE_INSTALL_TOOLThe password is set during installation. Since TYPO3 14, you can set it or have a new one generated on the command line with install:password:set. This only works if additional.php does not override the value. In the Install Tool itself, there is the card Change Install Tool Password in the Settings module. Do not confuse this with backend:resetpassword: that command resets the password of a backend user.
vendor/bin/typo3 install:password:setIf the backend is broken, for example after an error in an extension, the parameter __typo3_install on the start address of the website helps. It leads to the installer or the maintenance tool. You still need the file ENABLE_INSTALL_TOOL and the password.
Installation-wide options and maintenance lock
You change most system values in the Settings module with the card Configure Installation-Wide Options. TYPO3 then writes them to settings.php. These options matter to Mara:
lockSSLin the BE section forces HTTPS for the backend. TYPO3 redirects requests without HTTPS to the encrypted address.cookieDomainin the SYS section decides which domain login cookies apply to. With the value dot musikschule-lindenau.example, all subdomains share the session. Separate values for frontend and backend are set withcookieDomainin the FE and BE sections.sessionTimeoutin the BE section ends an inactive backend session. The default is 28800 seconds, that is, 8 hours. For frontend users, the same key in the FE section applies, with 6000 seconds.- In the GFX section you choose the image program, GraphicsMagick or ImageMagick, and its path. In the MAIL section you configure sending email.
You check whether image processing really works in the Environment module under Image Processing. There, TYPO3 creates test images and shows them next to reference images. Under Configuration Presets in the Settings module, there are also ready-made bundles, such as Live and Debug for error output.
During maintenance you want to stop editors from working at the same time. For this, there is adminOnly in the BE section:
- The value 0 is normal operation. All users may log in.
- The value 1 lets only admins and system maintainers into the backend. The command line is locked as well.
- The value 2 also lets only admins into the backend. Command line calls, such as scheduler tasks, keep running.
- The value minus 1 shuts the backend down for everyone.
A second lock is the file LOCK_BACKEND. The command backend:lock creates it, and backend:unlock removes it. It locks the backend for everyone, admins included. If the file contains an address, TYPO3 redirects backend requests there, such as a maintenance page. In Composer installations, it lives in the folder var/lock by default. If the lock should survive a deployment, the release folders must share this folder. Unlike ENABLE_INSTALL_TOOL, LOCK_BACKEND never expires on its own.
Showing or hiding errors
When PHP reports an error or an exception occurs, TYPO3 decides how much of it becomes visible. The production exception handler shows only a short message. The debug exception handler shows details with a stack trace. The choice is controlled by displayErrors in the SYS section:
- The value 1 displays errors and uses the debug exception handler.
- The value 0 displays no errors and uses the production exception handler.
- The value minus 1 is the default. Then the IP address of the caller decides.
With the value minus 1, TYPO3 compares the IP address with devIPmask in the SYS section, the list of addresses that may see debug output. The default is 127.0.0.1 and the IPv6 address for localhost. If the address matches, there are details, otherwise the short message.
The Development context is the place for detailed error messages in the browser. The context alone does not switch the details on, though. Mara sets displayErrors to 1 in additional.php for this. In the Settings module, Configuration Presets offers the Debug bundle for this.
Live, the opposite applies:
- displayErrors is 0, as in the Live bundle.
- devIPmask contains at most a few internal addresses, or stays empty. An asterisk as the value would allow debug output for everyone.
- Errors are logged, and someone checks the log regularly.
Where do errors end up? In a Composer installation, TYPO3 writes them to the folder var/log, into a file named typo3, an underscore and a short hash. In addition, the Log module under Administration shows entries from the table sys_log.
The page cache
A cache is a temporary store. It keeps results that were already computed, so the next request is faster. The data itself stays in the database, and the cache neither replaces nor deletes it.
For integrators, the most important cache is the page cache. It lives on the server, not in the visitors' browsers. On the first request, TYPO3 renders the page and stores the result, and after that it delivers the stored version.
This leads to a typical puzzle: an editor changes a headline, but the visitor still sees the old one, because it is still in the cache. Usually TYPO3 clears the cache of the affected page automatically when content is saved. But if the content also appears on another page, for example as a teaser on the home page, that page's cache stays.
Clearing by hand works in two ways:
- The lightning bolt icon of a page in the Layout module clears only that page's cache.
- In the lightning bolt menu in the top bar, Flush frontend caches clears the page caches of the whole installation. Afterwards every page must be rendered again, which puts more load on the server for a while. Users and extensions are not affected.
Flush all caches clears further caches as well. The Maintenance module offers the most thorough way, and on the command line there is cache:flush.
How long does a page stay in the cache? The default for all pages is set by config.cache_period in TypoScript, in seconds. Since TYPO3 14.3.1, the default is 31536000 seconds, that is, 365 days. Before that it was one day, that is, 86400 seconds, and many guides still say so. For a single page, you set the duration in the page properties on the Behaviour tab, next to the cache tags of the page. A value greater than 0 on the page takes precedence over config.cache_period.
Content with a start or stop time shortens the lifetime by itself, so that it appears or disappears on time.
You can switch off the page cache entirely by setting config.no_cache to 1. That only makes sense during development, because then every page is rendered completely on every request. A “no cache” checkbox in the page properties has not existed since TYPO3 9.
Targeted clearing and dynamic parts
The home page of the music school shows teasers of the next concerts. The editors maintain the concerts themselves in a folder. When they save a concert there, TYPO3 only clears the cache of this folder. The home page keeps showing the old state.
The solution is TCEMAIN.clearCacheCmd in Page TSconfig. It clears additional page caches when a record is saved. These values are allowed, several of them separated by commas:
- Page IDs, for example 1 for the home page.
- The keyword pages for all page caches.
- The keyword all for all caches.
- The prefix cacheTag with a colon and a tag name.
Cache tags are labels on cache entries. With one tag, you clear many entries at once, without knowing their page IDs. A page gets a tag through the Cache Tags field in its page properties, or in TypoScript through the stdWrap function addPageCacheTags.
TCEMAIN.clearCacheCmd = 1, cacheTag:concerts- Mara enters the value concerts in the Cache Tags field of the home page and of the Events page.
- In the Page TSconfig of the concert folder, she sets clearCacheCmd to cacheTag:concerts.
- When the editors save a concert, all pages tagged this way lose their cache and show the new date on the next request.
Clearing the whole cache every night, or switching caching off, would be the worse choice.
Dynamic parts: The header of the home page should show a time that is correct on every request. For this, Mara outputs this part as COA_INT or USER_INT. These uncached objects are stored in the cache only as placeholders. TYPO3 renders them again on every request, while the rest of the page stays cached. config.no_cache, by contrast, would leave the whole page uncached and hurt performance.
page.30 = COA_INT
page.30.10 = TEXT
page.30.10.data = date:H:iThe Admin Panel
The Admin Panel is a bar at the bottom of frontend pages. It comes from the system extension adminpanel, Composer package typo3/cms-adminpanel. Only users who are logged in to the backend in the same browser can see it.
Switching it on takes two parts:
- In TypoScript, you set
config.admPanelto 1. The panel then appears for logged-in admins. - Other backend users also need
admPanel.enablein User TSconfig, for themselves or for their group. WithadmPanel.enable.allset to 1 they get all areas, withadmPanel.enable.previeworadmPanel.enable.cacheonly single ones.
Admins have admPanel.enable.all by default. So for editors, config.admPanel alone is not enough, but they do not need admin rights either.
The bar directly shows TypoScript messages, load time and memory usage, errors and warnings, and the number and duration of SQL queries, but no visitor numbers. Expanded, it has these areas:
- Info shows the page ID, the page type, the cache status and the number of USER_INT objects.
- TypoScript shows the time measurement of the TypoScript rendering.
- Debug shows all SQL queries with their duration, as well as log entries and events.
- Preview offers “Simulate time” for scheduled content, “Simulate user group” for protected content, and showing hidden pages and records.
- Cache switches caching off, clears the cache of the current page or the whole frontend cache.
With the Settings button, you set the options of these areas, such as the simulated time. The panel cannot simulate the application context, only time and user group.
Key points
- TYPO3 writes the system values to settings.php. additional.php is loaded afterwards, wins and holds your own logic and credentials.
- The context comes from the environment variable TYPO3_CONTEXT, and without it Production applies, on the command line too.
- Only system maintainers see the modules under System, in the Development context every admin.
- The Install Tool without the backend needs the password and the file ENABLE_INSTALL_TOOL, which expires after one hour unless it contains KEEP_FILE.
- adminOnly set to 2 lets only admins into the backend and keeps the command line running. LOCK_BACKEND locks everyone out.
- displayErrors set to 0 hides errors. With the default minus 1, devIPmask decides.
- config.cache_period sets the default lifetime, and the page properties take precedence.
- clearCacheCmd and cache tags clear further pages on saving, while COA_INT and USER_INT keep parts dynamic.
- The Admin Panel needs config.admPanel and, for non-admins, admPanel.enable in User TSconfig.
Terms
- Application context
- The environment TYPO3 runs in, that is, Production, Development or Testing.
- System maintainer
- An admin who may open the maintenance modules under System.
- ENABLE_INSTALL_TOOL
- A flag file that opens standalone access to the Install Tool for one hour.
- LOCK_BACKEND
- A flag file that locks the backend for all users.
- Sudo mode
- Entering your password again before TYPO3 allows a sensitive action.
- devIPmask
- The list of IP addresses that may see debug output.
- COA_INT
- A content object that is rendered again on every request.