What can you expect in this article?
- We explain which files are relevant for a Contao backup.
- You will learn what you should backup before a bugfix update
- We will give you tips on how to perform and automate backups
Contents
What makes a complete Contao backup?
Basically, a backup consists of certain directories, files and an export of the database.
To help you understand which files and directories you should back up, we will first explain the directory structure of a typical Contao installation.
(see also: Developer Documentation)
Structure of a Contao 4.13 installation performed via Contao Manager
| File / Directory | Explanation | Backup needed |
|---|---|---|
assets/ |
JavaScript, images, CSS files from Contao and extensions | No |
config/ |
Configuration files of the application | Yes |
contao-manager/ |
Configuration, cache and log files of the Contao Manager | If requiredusers.json |
files/ |
All files that are managed via the Contao file manager. | Yes |
system/ |
Required for Contao 3 compatibility | Only partiallyconfig/localconfig.php |
templates/ |
Customized Contao templates | Yes |
var/ |
Automatically generated files, such as the application cache and log files | No |
vendor/ |
Composer's vendor directory contains all packages and required dependencies (incl. Contao core, Symfony and Contao extensions) | No |
public/ or web/ |
Public document root and entry point. Includes symlinks and other public resources | No |
composer.json |
Project configuration defines which packages and versions belong to the Contao installation and may be installed | Yes |
composer.lock |
Is generated by "composer update" or the Composer Cloud and contains a complete list of all packages and dependencies with exact version information, which are installed. This file is processed by "composer install" | Yes |
Other relevant files and directories that may have been created manually and are not present in every installation
| File / Directory | Explanation | Backup needed |
|---|---|---|
contao/ |
Adaptations to Contao (e.g. DCA fields, language files) | Yes |
src/ |
Individual application-specific source code | Yes |
system/modules/* |
Old Contao 3 modules | Check Only modules installed manually via SFTP, no symlinks! |
public/ or web/ |
Public document root and entry point. Includes symlinks and other public resources | Check Only manually added or modified files e.g. .htaccess |
Summary
For a complete backup you need the directories: "config", "files", "templates" and the files "localconfig.php", "composer.json" and "composer.lock".
If you are still using old Contao 3 modules in your project, you have to backup the corresponding modules from the directory "/system/modules".
If you have made customizations, you should also backup the directories "contao" and "src".
If you have made manual changes to the ".htaccess", it is advisable to back them up as well.
If you want, you can also backup the "users.json" of the Contao Manager. However, this is only important if you want to back up the access data to the Contao Manager.
Do I really have to back up all files?
For larger projects with many files, the "files" folder can quickly become several hundred MB or even GB in size. This raises the question of whether you always need to create a complete backup.
It makes sense to have a complete backup if you do not otherwise create regular backups. Before major changes and version changes, a complete backup also makes sense.
However, we do not see any added value for a full backup especially for small bug fix updates, such as from Contao 4.13.24 to 4.13.25. Usually, there are no templates changes here. In addition, CSS adjustments are usually not necessary either.
Therefore, we only back up "composer.json", "composer.lock" and create a current dump of the database before a bugfix release. Then we install our updates via trakked.
If unexpected problems occur, we can restore the previous version very quickly with the help of "composer.lock" and the database.
So much for the theory. Let's move on to the practice.
How can you make a backup?
There is no ONE right way. It depends on your skills, the hosting and your workflow. We would like to briefly show you a few possibilities and ideas here.
1) Backup via SFTP and phpMyAdmin
This will certainly sound familiar to you.
Files and directories
To do this, connect to your server with an SFTP client (e.g. Filezilla, WinSCP) and transfer the relevant files locally or copy them to another directory on the server.
Alternatively, you can also use the hoster's web FTP and download or copy the relevant files.
Backup database
Here you can use phpMyAdmin. This tool is available from almost every hoster. You select your Contao database and export it with phpMyAdmin. Since Contao 4.13, an automatic backup is saved with every database migration you perform with the Contao Manager. By default, the backups are stored and managed in «var/backups».
If you use Contao 4.13 and trakked, you automatically get a minimal backup for your installation. This is because trakked saves the latest "composer.json" and "composer.lock" with every update, which you can download if needed. Contao 4.13 also create an automatic backup for every database migration you perform via the Contao Manager. So, you have everything you need to restore your Contao system to an older version in case of an emergency.
2) Backup via console
For this, you need SSH access to your server. This should be available with most hosters today.
Backup files and directories
For this you can use the command "cp" and copy the corresponding files.
This could look like this before a bugfix update:
# Login to server ssh user@domain.ch
# Change to the backup directory cd public_html/backup/domain.ch
# Create new directory mkdir 4.9.14
# Change to public_html directory cd ../../public_html
# Copy files from Contao to backup cp domain.ch/composer.json backup/domain.ch/4.9.14 cp domain.ch/composer.lock backup/domain.ch/4.9.14/
# Dump database mysqldump -h localhost -u username -p --opt databasename | gzip -c > backup/domain.ch/4.9.14/mysqldump.sql.gz
Since Contao 4.13 you can also use the command «contao:backup:create» for a database backup. You can find more information about this in the Contao manual.
To optimize these steps, you can also create a shell script that you can prepare and simply run as needed or regularly via CronJob.
Andreas Fieger, for example, provides a ready-made script on his GitHub account.
3) Backup via extension
In addition, there are numerous extensions that can help you with the backup.
With most extensions, however, only the database is backed up. On YouTube you can find a video on backing up data with BackupDB.
There are numerous other options. Depending on the hoster, these include a backup or snapshot function as well as deployment tools or external backup solutions.
In summary
For a simple bugfix release, a backup of "composer.json", "composer.lock" and the database is sufficient. With trakked and Contao 4.13 you already have this minimal backup out of the box. Otherwise, you can perform the backup in different ways. The important thing is that you take care of it.
How do you backup your Contao installation?
Feel free to send us your feedback via Slack, as a comment or via email.
