Study guide · Server and Command Line
Server and command line: the craft beneath TYPO3
Every TYPO3 website runs on a server. On this page you set up a server together with the integrator Mara. Afterwards you can move around the shell with confidence, create cron jobs, read and set file permissions and recognise errors by their status code. You also learn how TYPO3 manages files and images, how it anonymizes IP addresses and how Git keeps track of your project.
The example: the server of the Lindenau music school
Mara builds the website of the Lindenau music school as a Composer project with TYPO3 14.3. Her site package is called lindenau_site, and its Composer package is lindenau/site. It lives in the packages folder of the project.
Now the website moves to a Linux server. Mara logs in via SSH and lands on the command line, also called the shell. There is no mouse and no recycle bin, and every command takes effect immediately.
First steps on the command line
You are always in a current directory. The command pwd shows where that is. With ls you list the contents of a directory. The option l makes the list detailed, including permissions and owner. With cd you change the directory. Two dots as the target take you one level up. Without an argument, cd takes you to your home directory. The command cat prints the contents of a file.
pwd
cd /var/www/lindenau
ls -l
cd ..
cat /var/www/lindenau/composer.jsonRelative paths refer to the current directory. Only a path that starts with a slash is absolute. So the same command can hit something different depending on where you are.
Creating, copying, deleting:
mkdircreates a directory, and with the option p several levels at once. It never deletes anything that exists.touchcreates an empty file. For an existing file it updates the timestamp.cpcopies files. It only copies a directory with its contents when you add the option r, which stands for recursive.mvmoves or renames a file.rmdeletes files, and with the option r also a directory with its contents.rmdironly deletes empty directories.
mkdir -p backup/2026
touch notes.txt
cp -r config backup/2026/
mv old.txt new.txt
rm -r tmp-testHelp: You open the manual page of a command with man followed by the command name. Many commands also show a short help with the option help, written with two dashes in front. A slash followed by a question mark is a Windows habit.
man ls
ls --helpAn empty variable as a trap: In an old script, one line deletes a folder taken from a variable. If the variable is empty, only the slash is left, and the command hits the root of the file system. The option f suppresses every confirmation prompt.
rm -rf $ORDNER/That is why safe scripts first check that the variable is filled, and they work with absolute, checked paths.
Cron: commands on a schedule
The cron daemon is a service that starts commands on a schedule. Such a time-based command is called a cron job. A user's list of cron jobs is called the crontab. You edit it with crontab and the option e, and you display it with the option l.
crontab -e
crontab -lEach line has five time fields, followed by the command. The order is minute, hour, day of month, month and weekday. A star means every value. The classic crontab has no seconds. For the weekday, 1 means Monday, and both 0 and 7 mean Sunday.
Two examples from Mara's server:
- The line with zero, three and three stars starts the backup every day at 3 a.m.
- The line with 30, 2, two stars and a 1 starts a report every Monday at 2:30 a.m.
Cron and TYPO3: TYPO3 uses cron to trigger the Scheduler regularly. A single entry that calls scheduler run every few minutes is enough. The Scheduler then finds the due tasks itself.
*/5 * * * * /usr/bin/php8.4 /var/www/lindenau/vendor/bin/typo3 scheduler:runFile permissions on Linux
Every file has an owner and a group. Permissions exist separately for the owner, the group and everyone else:
- The r stands for read.
- The w stands for write.
- The x stands for execute. On a directory, x allows you to enter it.
The detailed list of ls shows the permissions. The first character gives the type: a dash for a file, a d for a directory and an l for a symbolic link.
chmod changes the permissions, chown the owner and chgrp the group. As a number, each digit is the sum of 4 for read, 2 for write and 1 for execute. With 755, the owner of a directory may do everything. Everyone else may read and enter it.
chmod 755 public
chown -R mara:www-data varWhat TYPO3 sets: New files get their permissions from the setting fileCreateMask in the SYS section, with the default 0664. New folders get them from folderCreateMask, with the default 2775. The leading 2 is the setgid bit: new files in the folder inherit its group. This lets Mara and the web server work in the same group.
Where the web server must write:
- In the folder
var, TYPO3 stores caches, logs and locks. - In the folder
public/fileadmin, the editors keep their uploads. - In the folder
public/typo3temp, public temporary files live.
Composer manages the folder vendor, and the web server does not write there. The folder config only needs to be writable when you save settings or sites in the backend.
TYPO3 folders and files
In an extension such as lindenau_site, every folder has a fixed purpose:
- The folder
Classesholds the PHP classes. Composer loads them following PSR-4. - The folder
Configurationholds the configuration, for example the site set and TCA. - The folder
Resources/Privateholds templates and language files. - Only the folder
Resources/Publicis made public. CSS and JavaScript live there.
In the project, TYPO3 creates some folders itself. The folder var/cache holds caches that can be regenerated. The folder var/log holds logs. Processed images go into a folder _processed_ in the respective file storage. You never delete the folder var completely, you only clear it selectively. No cache flush touches the folder fileadmin, because it belongs to the editors. Under System, Maintenance, the card “Remove Temporary Assets” removes, among other things, processed image variants.
Umlauts in file names: A teacher uploads the plan for “Flöte”, and the file name arrives oddly renamed. Two settings in the SYS section work together here. With UTF8filesystem, TYPO3 stores file names in UTF-8. That needs a UTF-8 capable locale, which you set in systemLocale. Otherwise special characters cause problems. New installations set UTF8filesystem to true.
HTTP status codes
The server answers every request with a three-digit status code. The first digit names the group:
- Success starts with 2. 200 means OK.
- Redirects start with 3. This group also includes 304, Not Modified: the browser's stored copy is still valid.
- Client errors start with 4. 404 means not found. 403 means forbidden, for example on a page only for logged-in users.
- Server errors start with 5. You find them in the log files.
Server errors in the log: 500 is an internal error, for example a PHP error. 502 reports a bad response from an upstream server. 503 means temporarily unavailable and suits maintenance. 201 means created, and like 304 it is not an error.
Redirects:
- 301 is permanent, 302 is temporary.
- 307 is temporary and requires the same method. A POST stays a POST.
- 308 is the permanent counterpart of 307.
In the site configuration you can set your own error pages for individual codes, for example for 404 and 403.
Anonymizing IP addresses
TYPO3 stores IP addresses in some places, for example in the table sys_log. An IP address can be linked to a person, so it is personal data. Making it unrecognisable after a set period protects visitors and lowers the data protection risk of old logs.
The global setting ipAnonymization in the SYS section applies to addresses stored through the TYPO3 API:
- The value 0 switches anonymization off.
- The default value 1 sets the last byte of an IPv4 address to zero, and for IPv6 it masks the interface ID.
- The value 2 masks the last two bytes of an IPv4 address, and for IPv6 also the SLA ID.
This setting does not apply to the table sys_log. TYPO3 stores the full address there. That is why old entries need a task of their own.
The Scheduler task “Anonymize IP addresses in database tables” handles addresses that are already stored. Mara creates it in the Scheduler module and fills in three things:
- The table, for example sys_log.
- The number of days. Only older records are anonymized.
- The mask level, that is one or two bytes. Two bytes is the preset.
The task tells the age of a record from a timestamp field in the table.
Custom tables: The music school stores the IP address of trial lesson sign-ups in a table of its own. Since TYPO3 14, Mara registers it with a TCA override. The file targets the table tx_scheduler_task, specifically the type of the IP task. Under taskOptions and tables she names the IP field and the timestamp field.
$GLOBALS['TCA']['tx_scheduler_task']['types'][IpAnonymizationTask::class]['taskOptions']['tables']['tx_lindenausite_trial'] = [
'dateField' => 'crdate',
'ipField' => 'ip_address',
];The old way through the global settings under SC_OPTIONS is deprecated and will stop working in TYPO3 15.
Regular expressions
A regular expression describes a pattern that you use to find, check or replace text. In TYPO3 you meet them in redirects with regex and in validators. PHP uses the PCRE flavour, where the pattern sits between two delimiters, often hash signs.
- The caret anchors the pattern at the start of the text, the dollar sign at the end.
- Without an anchor, the match may be anywhere in the text.
- A dot stands for any character. You write a real dot with a backslash in front.
- Backslash d stands for a digit, backslash w for a word character.
- Square brackets with a, b and c match exactly one of these characters.
- Plus means one or more times, star means zero or more times, and the question mark means zero times or once.
- Round brackets form groups that you can refer to later.
- Dot and star together are greedy and grab as much as possible.
\d+
^index\.html$
[abc]
#^/news/\d+$#You can test patterns with tools such as regex101. They show which parts of a text match.
Processing images on the server
TYPO3 scales, crops and converts images on the server. For this it calls GraphicsMagick or ImageMagick. The system requirements recommend GraphicsMagick, while the preset value is ImageMagick. Program and path are set in the GFX section with processor and processor_path. For images drawn by GIFBUILDER, TYPO3 also uses the PHP extension gd.
TYPO3 stores a generated variant in the folder _processed_ and delivers it again on the next request. This saves computing time.
Testing: Under System, Environment, the card “Image Processing” creates test images and compares them with reference images.
Files in TYPO3: FAL
FAL stands for File Abstraction Layer. This layer separates file management from physical storage. A storage can be a local folder such as fileadmin. Through drivers it can also be a cloud service. So files do not have to live in fileadmin.
- The table sys_file is the index. It describes every file exactly once.
- The table sys_file_metadata holds metadata such as title and alternative text.
- The table sys_file_reference records every use of a file, for example in a content element.
So a content element does not store a file path as text. It points to a reference instead. If you rename or move a file in the backend, all content stays valid. In the reference you can override title and alternative text per use.
Bypassing the backend: Mara replaces the trial lesson flyer via FTP directly in fileadmin. In the backend, size and thumbnails are wrong afterwards. The FAL index is outdated, because TYPO3 did not notice anything. The Scheduler task “File Abstraction Layer: Update storage index” or a new upload brings it back in sync. That is why you best move files in the Media module.
Git: keeping versions under control
Git is a version control system. It stores the history of all files in a repository. This lets you trace, undo and merge changes.
git initcreates a new repository in the current directory.git clonecopies an existing one.git addstages changes, andgit commitsaves them as a new state.git pushsends local commits to the remote repository.git pullfetches changes and merges them.git fetchonly fetches them.
Branches: A branch is a line of development on which you work separately from the main branch. Mara builds the new course programme on a branch of its own. Afterwards she merges it into the main branch.
Tags: A tag marks a specific state, for example a release. Unlike a branch, it does not move on.
git init -b main
git add .
git commit -m "First version"
git remote add origin https://git.example.org/lindenau/site.git
git push -u origin main
git switch -c kursprogramm
git switch main
git merge kursprogramm
git tag v1.2.0Conflicts: If both branches changed the same lines in different ways, Git reports a conflict during the merge. Git cannot decide which change wins. Mara resolves it in the marked files, adds them with git add and completes the merge with a commit.
What stays out of the repository: In a Composer project, the file .gitignore typically lists three folders:
- The folder
vendor, because Composer builds it from composer.lock. - The folder
varwith runtime data. - The folder
public/fileadminwith the editors' files.
On the other hand, composer.json, composer.lock, the folder config and the site package in the folder packages belong in the repository. Credentials never do.
Key points
- The command line has no recycle bin. You copy and delete directories recursively with the option r.
- A crontab line has five time fields: minute, hour, day, month and weekday. For the Scheduler you give PHP with its full path.
- The permissions r, w and x count 4, 2 and 1. TYPO3 sets 0664 for files and 2775 for folders.
- The web server writes to var, fileadmin and typo3temp, not to vendor.
- Browsers cache 301, so TYPO3 uses 307 for automatic redirects.
- The Scheduler task anonymizes IP addresses by table, period and mask level. Since TYPO3 14 you register custom tables via TCA.
- Image variants live in _processed_ and are reused.
- FAL separates file, metadata and use. Content points to references, not to paths.
- The gitignore contains vendor, var and fileadmin, but not composer.lock.
Terms
- Cron job
- Command that the cron daemon starts on a schedule.
- Setgid bit
- Permission on a folder that makes new files inherit the folder's group.
- Status code
- Three-digit number with which the server reports the result of a request.
- IP anonymization
- Masking part of an IP address so that it can no longer be linked to a person.
- Regular expression
- Pattern that describes and finds text.
- FAL
- File Abstraction Layer, the layer between TYPO3 and the file storages.
- Branch
- Line of development in Git.
- Tag
- Fixed marker for a specific state in Git.