Study guide · System Configuration and Caching

Configuring, maintaining and speeding up TYPO3

As of November 15, 2026 · TYPO3 14.3 LTS · about 25 min read

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.php in the core extension. You never change this file.
  • The file settings.php in the folder config/system contains everything that differs from the defaults.
  • The file additional.php in the same folder is loaded afterwards and can override any value.
Where TYPO3_CONF_VARS comes from additional.php maintained by hand, PHP logic loaded last, wins settings.php written by TYPO3 when saving in the Settings module, regenerated DefaultConfiguration.php defaults in the Core never edit loaded in order settings.php and additional.php live in config/system
Whatever is loaded later wins. The additional.php has the last word.

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;
}
Code example for additional.php. If the context is Development, Mara sets the DDEV database credentials. Otherwise, she forces HTTPS for the backend.

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/Staging
Apache example. The line sets the environment variable TYPO3_CONTEXT to the sub-context Production Staging.
TYPO3_CONTEXT=Development vendor/bin/typo3 cache:flush
Command line example. The cache flush command runs explicitly in the Development context here.

You 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 = applicationcontext
TypoScript example. The first condition checks for the Development context, the second for any context starting with Production. Below, a TEXT object outputs the context through getText.
base: 'https://www.musikschule-lindenau.example/'
baseVariants:
  - base: 'https://lindenau.ddev.site/'
    condition: 'applicationContext == "Development"'
Excerpt from the site configuration. The normal base is the live address. A variant sets the DDEV address in the Development context.

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.
Two ways to the maintenance tools With backend login Without backend login Adminnever editors System MaintainerDevelopment: every admin Production: sudo modere-enter password /typo3/installfollows the entryPoint ENABLE_INSTALL_TOOLexpires after 60 minutes Install Tool passwordown password, as a hash Maintenance, Settings, Upgrade, Environmentthe same tools either way Backend broken: parameter __typo3_install
With a backend login through the modules under System, without a login through file and password.

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_TOOL
Command line example. The first command creates the file ENABLE_INSTALL_TOOL in the folder var transient. The second writes KEEP_FILE into it so that it stays.

The 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:set
Command line example. The command sets a new Install Tool password.

If 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:

  • lockSSL in the BE section forces HTTPS for the backend. TYPO3 redirects requests without HTTPS to the encrypted address.
  • cookieDomain in 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 with cookieDomain in the FE and BE sections.
  • sessionTimeout in 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.

Who sees the error details? displayErrors 1 -1 0 IP address indevIPmask? Yes No Debug handlerdetails with stack tracefor development only Production handlershort messagelive for visitors The default is minus 1, devIPmask holds localhost.Errors are also logged in var/log.
displayErrors picks the handler. With the default minus 1, devIPmask decides.

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
Page TSconfig for the concert folder. On saving, the cache of page 1 is cleared, plus every page with the tag concerts.
  1. Mara enters the value concerts in the Cache Tags field of the home page and of the Events page.
  2. In the Page TSconfig of the concert folder, she sets clearCacheCmd to cacheTag:concerts.
  3. 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:i
TypoScript example. An uncached content object COA_INT contains a TEXT object that outputs the current time.

The 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.admPanel to 1. The panel then appears for logged-in admins.
  • Other backend users also need admPanel.enable in User TSconfig, for themselves or for their group. With admPanel.enable.all set to 1 they get all areas, with admPanel.enable.preview or admPanel.enable.cache only 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.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TYPO3 Explained 14.3, chapters System configuration (settings.php, additional.php), Application Context, Install Tool, Global TYPO3 configuration options, Error and exception handling, Caching
  • Getting Started 14.3, System Maintainer Area and access without the backend
  • TypoScript Reference 14.3, config (cache_period, no_cache, admPanel), conditions and getText applicationcontext
  • TSconfig Reference 14.3, TCEMAIN.clearCacheCmd and admPanel
  • Documentation of the system extension adminpanel 14.3
  • Changelog TYPO3 14.0, Install Tool follows backend routing (107536) and command install:password:set (104058)
  • Source code TYPO3 14.3 (typo3/cms-core, cms-backend, cms-install, cms-frontend, cms-adminpanel), checked for system maintainers, sudo mode, ENABLE_INSTALL_TOOL, adminOnly, LOCK_BACKEND, displayErrors, cache lifetime and clearCacheCmd

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications