Contao¶

Contao is a free, web-based Open Source Content Management System (CMS) written in PHP and distributed under the LGPL 3.0 or later licence.

Contao is used to build and manage professional websites of different types and size ranges that are easy to maintain.

As of Contao 4, it is based on Symfony, a popular high performance PHP framework for web development. Contao 4 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 are using PHP in the stable version 8.0:

[isabell@stardust ~]$ uberspace tools version use php 8.0
Selected PHP version 8.0
The new configuration is adapted immediately. Patch updates will be applied automatically.
[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.0'
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Your website domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.example
isabell.uber.space
[isabell@stardust ~]$

Create Database¶

Contao saves your data in a MySQL database. It is recommended to use an additional database (e.g. isabell_contao) instead of the default database.

[isabell@stardust ~]$ mysql -e "CREATE  DATABASE ${USER}_contao"
[isabell@stardust ~]$

Installation¶

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

Note

The given Composer command always installs the latest stable release. If you want to install a particular version, you must specify the version in the command as well, e.g.: composer create-project contao/managed-edition contao '42.23.*'

Composer will install all necessary dependencies Contao needs to run. This can take some time though.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ composer create-project contao/managed-edition contao
Installing contao/managed-edition (42.23.1)
  - Installing contao/managed-edition (42.23.1): Downloading (100%)
Created project in contao
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
[...]

[isabell@stardust isabell]$

Next, remove the unused DocumentRoot and create a new symbolic link to the Contao web/ subdirectory. Again, replace contao by the folder name where the Contao project files sit in.

[isabell@stardust isabell]$ rm -f html/nocontent.html; rmdir html
[isabell@stardust isabell]$ ln -s /var/www/virtual/$USER/contao/web/ html
[isabell@stardust isabell]$

Configuration¶

Contao Install Tool¶

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

Point your web browser to your website URL and append /contao/install (e.g. https://isabell.example/contao/install) to run the Contao install tool.

Note

The URL fragment /contao/install is only a Contao route and not a physical path within your installation.

Step 1: When you run the Contao install tool the first time, the web based installer will prompt to set a new password. For all future accesses, the Contao install tool will ask for this password again.

Step 2: To configure your database connection, you need to enter the MySQL database credentials:

MySQL hostname (use localhost)

MySQL username (equals your Uberspace username, e.g. isabell)

MySQL password

Contao database name (e.g. isabell_contao)

Step 3: Update the database (this will create the database table structure).

Step 4: Create a Contao back end administrator account.

You have successfully installed the Contao CMS on Uberspace 7!

Contao Back End¶

Point your web browser to your website URL and append /contao (or /contao/login) to open the Contao back end login mask (e.g. https://isabell.example/contao/login)

Log into the Contao back end by entering the credentials of the administrator account.

Updates¶

Note

Check the GitHub repository releases and the update feed regularly to stay informed about new updates and releases. Also read the news and announcements posted on contao.org.

To update an existing Contao installation just perform a Composer Update in the root directory of your application (e.g. /var/www/virtual/$USER/contao/). This will update the Contao Managed Edition core application and all its dependencies as well as all your installed third-party packages:

[isabell@stardust ~]$ cd /var/www/virtual/$USER/contao/
[isabell@stardust contao]$ composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
[...]

[isabell@stardust contao]$

Warning

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

Tested with Contao 4.11.0 / Uberspace 7.9.0.0

Written by: xchs <https://github.com/xchs>, luto <http://luto.at>