SSH commands to back up and restore a (Contao) web project (backup)

This is an archive post. It will not be updated.

A typical Contao 4 installation is located, for example, in:

/home/demoprojekt/ (below that there is also the web folder, which the project’s domain should point to and which contains the contao-manager.phar.php).

Use SSH to change to the directory one level above Contao in order to run the SSH commands described below. In the example above, that means the folder:

/home/

SSH command to back up the Contao files on the web space

With this command, you create a compressed backup of the folders and files of your Contao project.
Important: You also need to back up the database (see the command further below)!

Let’s take a look at the basic command, which you still need to adapt to your situation:

tar -vczpf backup-demoprojekt-files_$(date +"%Y-%m-%d_%H-%M").tar.gz ./demoprojekt

What do the individual parts of the command mean?

tar tells the server to use the well-known program tape archiver to carry out the following actions. The advantage of this program over zip is that it can also save the user permissions set for folders and files, so that they are set correctly again when unpacking. However, this only works if the server on which the file is unpacked again supports UNIX file permissions.

-vczpf is a sequence of options to be applied as part of the command. Broken down, they mean:

v = Enable verbose output of the “work” tar is doing. You could also leave this option out, but I quite like to see the program doing its job. It is important that this option comes as early as possible among the options.
c = create an archive
z = additionally compress the archive with gzip so that it takes up even less space
p = remember the access permissions so that you can restore them when extracting
f = write the archive to the file named next. This option must be the last option in this sequence, otherwise you will get errors!

If you are interested in more of the available options, you will find a nice breakdown in the ubuntuusers wiki.

The instruction backup-demoprojekt-files_$(date +"%Y-%m-%d_%H-%M").tar.gz defines what the backup file should be called. Replace the term demoprojekt with the name of your project (without umlauts/special characters). This ensures that later on you will still know which projects your backup files belong to. The instruction that follows makes the server automatically write the current date and time into the file name. .tar.gz is the file extension needed for a tar file with additional gzip compression.

The final instruction ./demoprojekt specifies which folder (including subfolders and files) should be backed up (assuming that you are currently one level above the project folder in the structure). Replace the term demoprojekt with the real name of your project folder.

Once you have entered the folder name and the project folder correctly in the command, you can enter the whole command in the console and confirm it. The server now creates the desired file backup, which can take very different amounts of time depending on the size of the project. Just wait until the work is finished and the console shows you that it is ready for new commands.

Now you still need to back up the database…

SSH command to back up the Contao database on the web space

With this command, you create a compressed backup of the MySQL database of your Contao project. If you don’t have the database credentials at hand, you will find them in the Contao project at /app/config/parameters.yml. You can open the parameters.yml with any common editor and will find the database credentials stored for Contao in it.
Important: You also need to back up the data from the web space if you haven’t done so yet (see the command above)!

The command for backing up the database is structured as follows and still needs to be adapted to your situation:

mysqldump -h DBHOST -u DBUSER -p DBNAME -r backup-demoprojekt-database_$(date +"%Y-%m-%d_%H-%M").sql

What do the individual parts of the command mean?

mysqldump tells the server to use the usually available program mysqldump to create a so-called logical backup of the database.
Important: To keep the database consistent, the mysqldump command locks the database while the backup is being created. So during this time, the database cannot be accessed. With a very large database and the correspondingly longer lock time for creating the backup, it is therefore advisable to make the backup at a time when no or only very few user visits to the website are expected.

-h DBHOST specifies where the server should look for the database. Replace DBHOST with the address of the database server. On many servers this is localhost, meaning the database server is located on the same server. In that case the section would read -h localhost. With other providers, the database server is hosted separately, so you enter an address such as example.yourprovider.com or an IP address here, and following this example the section would read -h example.yourprovider.com.
-u DBUSER specifies the name of the database user. Replace DBUSER with the corresponding user name from the credentials for the database. If the user is called demoprojekt1, for example, change the section to -u demoprojekt1.
-p stands for the password. However, you don’t enter the password visibly here; instead, you tell the server that it should ask you for it separately later for security reasons.
DBNAME specifies which database you want to select. So replace DBNAME with the name of the database from the credentials. If the database is called demoprojektdb, for example, change this section of the command to demoprojektdb.

The instruction backup-demoprojekt-database_$(date +"%Y-%m-%d_%H-%M").sql defines what the database backup file should be called. Replace the term demoprojekt with the name of your project (without umlauts/special characters). This ensures that later on you will still know which projects your backup files belong to. The instruction that follows makes the server automatically write the current date and time into the file name. .sql is the file extension needed for an SQL database.

When you now enter the whole command in the console and confirm it, the console will ask you for the password (“Enter password”). Type in the password and confirm with the Enter key. For security reasons, the password is not displayed, nor is its length.

As soon as you have entered and confirmed the correct password, the server starts backing up the database. How long this takes depends on the size of the database. For small web projects it is often done within a few seconds; for large projects it can take quite a while. That is why backups of large databases in particular should be made at times when as few users as possible are on the website, since the database is locked during the backup.

Once you have made both backups, you can download them from the server as usual, e.g. via FTP.

SSH command to unpack the Contao backup on the web space

I’m assuming that you made the backup as described above.
Upload the file to the web space where you want to install it. Please make sure to upload it, if possible, to a level that cannot be reached from outside, otherwise unauthorized persons could gain access to the file.

The command for unpacking the backup is structured as follows:

tar -xzf ./dateiname.tar.gz -C ./

What do the individual parts of the command mean?

I won’t go into every detail again here, since it is based on the same logic that was already relevant when packing the file backup.

The options -xzf mean:

x = The data should be extracted from the backup,
z = Since the backup was compressed with GZIP, it now also has to be decompressed with GZIP.
f = The data should be read from the specified backup file. This option must be named last so that no error occurs.

The part ./dateiname.tar.gz specifies where the file is located – starting from your current position on the server – and what it is called. In the example, it is in the directory you are currently in (./) and is called dateiname.tar.gz

-C ./ means that, when unpacking the file, the tape archiver should change to the directory specified next and unpack the backup there. In this specific example, the backup would be unpacked in the directory we are currently in.

Important: Remember to delete the .tar.gz file from the server after it has been successfully unpacked.

SSH command to import the Contao database backup into the database

I’m assuming that you made the backup as described above.
Upload the database backup to the web space where you want to install it. Please make sure to upload it, if possible, to a level that cannot be reached from outside, otherwise unauthorized persons could gain access to the file.

The command for importing the database backup is structured as follows:

mysql -hDBHOST -uDBUSER -p DBNAME < dateiname.sql

What do the individual parts of the command mean?

I won’t go into every detail again here, since it is based on the same logic that was already relevant when creating the database backup.
Here, too, you need the full credentials for the database into which the database backup should be imported.

Replace DBHOST with the address of the database, DBUSER with the database user and DBNAME with the database name.
Replace dateiname.sql with the correct name of the database backup.
If needed, you can also specify paths here, for example if the .sql file is located in a different directory.
After you submit the command, you will again be asked for the database password.

Important: Remember to delete the .sql file from the server after it has been successfully imported.

Other recommendations for unpacking/importing Contao backups

A few actions I recommend right after unpacking and importing:

Open the file parameters.yml in app/config/ and check whether the database credentials stored there are correct. It would be fatal if you mistakenly connected to the wrong database and, for example, overwrote a live project.
Check whether the localconfig.php in system/config/ still contains outdated settings and correct them if necessary.
Ideally, delete the complete prod and dev folders under var/cache, otherwise Contao might still use outdated data from them (also with fatal results).
Open the Contao Manager and check whether all packages are running.
Open the Contao Install Tool and check whether everything is OK there.
Log in to the Contao back end, go to System maintenance and have everything properly cleaned up again (especially symlinks etc.).

The symlinks etc. can also be handled via the console, but I may describe that in another post.