Installing and Configuring Contao CMS in ServBay Environment

Contao is a powerful open-source Content Management System (CMS) that is especially well-suited for building websites for small and medium-sized businesses, portals, or complex web applications. This guide will walk you through the detailed steps of installing and configuring Contao in ServBay—a convenient local web development environment for macOS—so you can quickly kick-start your Contao project development.

ServBay provides an all-in-one environment, integrating PHP, Composer, database services (such as MySQL/MariaDB and PostgreSQL), and web servers (including Caddy, Nginx, and Apache), greatly simplifying the process of setting up your local development environment. With ServBay, meeting Contao's technical requirements is a breeze.

What is Contao?

Contao is an open-source, PHP-based content management system (CMS) renowned for its user-friendliness, high flexibility, and robust administrative backend. It offers a wide array of features, including granular permissions management, version control, multilingual support, responsive image handling, and a modular architecture that makes extending functionality easy. The core philosophy of Contao is to provide a solid foundation, enabling developers and designers to build customized websites without having to start from scratch.

Prerequisites

Before you begin with the installation, please ensure the following requirements are met:

1. ServBay is installed and running: You need to have ServBay installed on your macOS system. Make sure ServBay is running, the required PHP version (Contao’s PHP version requirements can be found in the official Contao documentation), and the required database service (such as MySQL or MariaDB) are enabled in ServBay.
2. Composer: ServBay comes with Composer pre-installed, so there’s no need for a separate Composer installation.
3. Terminal access: You’ll need to use the Terminal to execute Composer commands.

Steps to Install Contao

This section will guide you through the detailed process of installing and setting up Contao in the ServBay environment.

Step 1: Create a Project Directory

First, navigate to ServBay’s default web root directory /Applications/ServBay/www and create a new subdirectory for your Contao project.

cd /Applications/ServBay/www
mkdir servbay-contao-app
cd servbay-contao-app

We’ll install Contao inside the servbay-contao-app directory.

Step 2: Create a Contao Project Using Composer

Contao recommends using Composer for installation and management. Since ServBay includes Composer by default, simply run the following command in your project directory to create a new Contao project:

composer create-project contao/managed-edition .

This command will download the latest version of the Contao Managed Edition and all its dependencies into your current directory (.). The process may take some time depending on your internet connection speed.

About Contao Managed Edition: contao/managed-edition is an official release of Contao that includes the core system along with recommended dependencies, and sets up a standard project structure. Note: when you install via managed-edition, the website’s public root will be the web subdirectory inside your project folder.

Step 3: Create a Database and User

Contao requires a database to store its content and configurations. ServBay provides handy database management tools such as phpMyAdmin or Adminer to create databases and users. Here, we'll use phpMyAdmin as an example:

1. Access phpMyAdmin provided by ServBay

   Open ServBay’s local interface at https://servbay.host/. Locate and click the link to phpMyAdmin.

2. Create a database user

   For security, it’s recommended to create a dedicated database user for your Contao project.

   a. Go to the user accounts page

   On phpMyAdmin’s main page, click the “User accounts” tab in the top menu.
   

   b. Add new user

   Click “Add user account” and fill in the following:
   
   *   **Username:** Enter a username you’d like to use for Contao’s database connection, e.g., `contao_user`.
   *   **Host:** Select `localhost`, restricting the user to local connections for added security.
   *   **Password:** Enter a **strong password**. Do not use simple passwords like `password123`. Use a password generator for better security.
   *   **Re-type:** Enter your password again.
   
   In the “Database for user account” section, usually choose “Create database with same name and grant all privileges”. This will create a database named `contao_user` and grant all privileges to this user.
   
   *   Ensure that “Grant all privileges” is checked.
   *   Click the “Go” button at the bottom to complete the user and database creation.
   

Step 4: Configure Your Site in ServBay

Next, you need to configure a website in ServBay that points to the Contao project directory you just created.

1. Open ServBay and add a new site

   Launch the ServBay app. Click the “Sites” tab in the sidebar, then click the “Add” button to create a new site configuration.

2. Fill in the site configuration details

   • Name: Choose a name that will help you recognize the site later, e.g., My Contao Site.
   • Domain: Set a local development domain. It’s recommended to use a .local or .servbay.demo suffix, e.g., servbay-contao.local. ServBay will automatically resolve this domain to your local system.
   • Site type: Select PHP.
   • PHP version: Select the PHP version that meets Contao’s system requirements (refer to Contao’s documentation).
   • Document root: This step is very important. When installing via Composer’s contao/managed-edition, all public files (including index.php) are in the web subdirectory within the project folder. So, set the full path to the web directory: /Applications/ServBay/www/servbay-contao-app/web.

3. Save your configuration

   After filling in all the details, click the “Save” button at the bottom of the ServBay interface. ServBay will now apply your new site configuration.

Step 5: Run the Contao Web Installer

With the site configured, you can now use your browser to run the Contao web installer.

1. Go to the installer page

   Open your browser and visit your configured domain with /contao/install at the end. For example: https://servbay-contao.local/contao/install.

   If everything is set up correctly, you’ll see the Contao installation page.

2. Enter database details

   The installer will prompt you for your database connection information. Fill in the database and user details you created in Step 3:

   • Database host: localhost
   • Database name: contao_user (if you chose to "create database with same name as user" in phpMyAdmin)
   • Username: contao_user
   • Password: The password you set for contao_user in Step 3

3. Enter admin details

   Configure your Contao admin’s username, password, email, and other settings as prompted. Be sure to choose a strong password.

4. Complete the installation

   Follow the remaining steps in the installer, which typically include setting up the database schema. Click the corresponding buttons (such as “Install” or “Finish”) to complete the installation.

Step 6: Verify the Installation and Log into the Backend

Once the installer is done, confirm that Contao is working correctly and try logging into its admin backend.

1. Visit the site frontend

   In your browser, go to your configured domain, e.g., https://servbay-contao.local/. You should see Contao’s default welcome page or a blank site (depending on default settings). This indicates your web server is set up correctly and the Contao frontend is accessible.

2. Access the Contao backend

   Visit the Contao backend login page, typically https://servbay-contao.local/contao.

   Log in using the admin username and password you set in Step 5. Once logged in, you’ll reach the Contao admin panel, where you can start creating content, installing extensions, and configuring your website.

Frequently Asked Questions (FAQ)

Q: What should I do if I get errors accessing https://servbay-contao.local/ or https://servbay-contao.local/contao/install?

A:

• Check if ServBay is running: Make sure the ServBay application is running and that the required PHP and web server (Caddy or Nginx) are started.
• Review the ServBay site configuration: Double-check your ServBay site configuration—especially the domain, site type, PHP version, and document root. Remember, the document root for contao/managed-edition projects should be the web directory inside your project folder.
• Check domain resolution: ServBay automatically handles .local domain resolution. If you used another domain suffix or still encounter issues, try restarting ServBay or check your system’s hosts file (although ServBay manages this automatically in most cases).
• Check web server logs: Look at the web server logs provided by ServBay (Caddy or Nginx). You may find more detailed error messages here.

Q: What if the database connection fails?

A:

• Check the database service status: Make sure the MySQL/MariaDB or PostgreSQL service is running in ServBay.
• Check your database credentials: Double-check the database host (localhost), database name, username, and password you entered in the Contao installer—all must exactly match what you created in phpMyAdmin.
• Check user permissions: Make sure your database user has all necessary privileges for the Contao database.

Q: What should I do if I encounter permissions errors during installation?

A: The Contao installer needs write permissions to certain directories. While ServBay’s default configuration is usually sufficient, if you encounter issues, you can set the necessary permissions in your project directory using the Terminal:

cd /Applications/ServBay/www/servbay-contao-app
sudo chown -R your_username:staff . # Replace your_username with your macOS username
sudo chmod -R 755 .
sudo chmod -R 777 var/ cache/ system/config/ # Contao may require write permissions here

Be cautious when using chmod 777—it’s not secure for production but is a common solution for resolving permissions issues in local development environments.

Conclusion

By following this guide, you should have successfully installed and configured Contao CMS in your ServBay local development environment. ServBay’s integrated stack takes the hassle out of managing Composer dependencies, database setup, and web server configuration—allowing you to focus on developing with Contao.

Now you can start creating content, designing pages, installing extensions and themes, and building your website through the Contao backend.

If you want to explore more about using Contao and its various features, please refer to the official Contao documentation.