Skip to content

Contao

Contao

License: LGPL 3.0

This guide is tested with Contao 5.7.5 on Uberspace 8.0.75. We can't guarantee it to work with newer versions.

Contao is a free, open-source Content Management System (CMS) written in PHP. Contao is used to build and manage professional websites of different types and size ranges that are easy to maintain.

It is based on Symfony, a popular high performance PHP framework for web development. Contao has been designed as a Symfony bundle, which can be used to add CMS functionality to any Symfony application.

Contao (formerly TYPOlight) was released for the first time in 2006 by Leo Feyer. Since then it has been continuously developed and it is actively maintained by the Contao Core Development Workgroup and other contributors.

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites

We're using PHP in version 8.4:

[isabell@moondust ~]$ uberspace tool version set php 8.4
OK: Set version of php to 8.4

Create Database

Contao saves your data in a MariaDB database. Create a database for your Contao installation:

[isabell@moondust ~]$ mariadb -e "CREATE DATABASE ${USER}_contao"

Document Root Preparation

Since Contao uses the subdirectory public/ as web root of your website you should not install Contao in your default Uberspace DocumentRoot. Instead, we install it next to that and use a symlink to make it accessible to the web:

[isabell@moondust ~]$ cd /var/www/virtual/$USER/
[isabell@moondust isabell]$ rm -r html
[isabell@moondust isabell]$ mkdir -p contao/public
[isabell@moondust isabell]$ ln -s contao/public html

Installation

Download the Contao Manager to your web root:

[isabell@moondust ~]$ cd /var/www/virtual/$USER/contao/public
[isabell@moondust public]$ wget "https://download.contao.org/contao-manager.phar.php"

Configuration

To complete the installation, you need to run the Contao Manager, which will guide you through the installation process.

Point your web browser to your website URL and append contao-manager.phar.php (e.g. https://isabell.uber.space/contao-manager.phar.php) to start the Contao configuration.

  1. Manager Account: When you run the Contao install tool for the first time, the web-based installer will prompt you to choose a new username and offers to create a passkey you can save in your password manager. If you prefer to use a password, click on the arrow and choose Use password for login before you click on Create Account.

  2. You can enable 2FA to provide additional protection for your account, which is recommended, but you also have the option to skip it for now.

  3. Warning

    Please skip the crossed-out part until this issue is fixed.

    The System Check will now evaluate whether all requirements are fulfilled. Next to Server Configuration you can click on Change and uncheck the setting Use the Composer Resolver Cloud if you want. For an average installation, your Asteroid provides enough resources to run Composer and this will prevent problems, if the Composer Cloud is not available. Click Save.

  4. The System Check will run again, and you can click on Setup, followed by Get started. On the Webserver Setup page, you can click on Continue because we've already made sure that the directory structure is correct. Now, select a version. If you have no special needs, it's a good idea to go with an LTS version. Click Install and wait until the installation completes.

  5. Database Configuration: To configure your database connection, you need to enter the MariaDB database credentials. The following command will show you your username and password:

    [isabell@moondust ~]$ my_print_defaults client
--user=isabell
--password=MySuperSecretPassword

    The other settings are:

    Server (:Port): localhost
Database Name: isabell_contao

    Click Save. In the next step, click Check database and once the process has finished, click Execute. After everything is complete, click Confirm & Close.

  6. Your database schema should now be up to date, so that you can click Continue.

  7. Backend Account: Create a Contao backend administrator account.

You have successfully installed the Contao CMS!

Contao Backend

Point your web browser to your website URL and append /contao to open the Contao backend login page (e.g. https://isabell.uber.space/contao)

Log in to the Contao backend by entering the credentials of your backend account.

Tuning

Contao has a backend search that makes it easy to find any kind of content. For technical reasons, this requires a cron job that runs every minute. Fortunately, your Asteroid lets you set this up, so if you want to use it, follow the next steps.

Install Search Engine

First, you'll need a search engine; several are supported. If you don't have specific requirements, Loupe is the best choice, since it only requires an additional SQLite database. Launch the Contao Manager and search for contao/loupe-bridge. Now install Loupe Bridge by clicking Add and then start the installation under PACKAGES by clicking Apply Changes. No further configuration is required after you've clicked Confirm & Close.

Add Cron Job

Open your cron table:

[isabell@moondust ~]$ crontab -e

Add the following lines (without deleting existing content):

MAILTO=""
* * * * * /usr/bin/php /var/www/virtual/isabell/contao/vendor/bin/contao-console contao:cron

Press Ctrl+O, then Enter, and finally Ctrl+X to save and exit.

Rebuild Search Index

Log in to the backend, navigate to the Maintenance page, and click Rebuild index under Back end search.

Updates

Note

Check the update feed regularly.

To update an existing Contao installation, start the Contao Manager again (e.g., by visiting https://isabell.uber.space/contao-manager.phar.php). If a new version of the Contao Manager is available, the System Check may prevent you from continuing. In this case, update the Contao Manager first by clicking Run Self-Update.

From time to time (and if you change the PHP version), you should run a full package update. To do this, click Update Packages under PACKAGES. Instead of confirming with Apply Changes, click the arrow next to it and select the Update all packages option.

Warning

The Contao Managed Edition and especially additional bundles and modules are not updated automatically, so make sure to regularly install security and maintenance updates.