How to Install CakePHP on Ubuntu 24.04

Table of Contents#

Prerequisites
Step 1: Update the System
Step 2: Install a Web Server (Apache)
Step 3: Install PHP and Required Extensions
Step 4: Install a Database (MariaDB)
Step 5: Install Composer (PHP Dependency Manager)
Step 6: Create a New CakePHP Project
Step 7: Configure Apache for CakePHP
Step 8: Set File Permissions
Step 9: Configure the Database (Optional)
Step 10: Test the Installation
Troubleshooting Common Issues
Conclusion
References

Prerequisites#

Before you begin, you will need:

A machine running Ubuntu 24.04.
A user account with sudo privileges.
Access to a terminal or command line.
An active internet connection.

Step 1: Update the System#

It's always a good practice to start by updating your system's package list and upgrading existing packages to their latest versions.

sudo apt update && sudo apt upgrade -y

Once the upgrade is complete, you can reboot the system if necessary, though it's often not required for a fresh install.

sudo systemctl reboot

Step 2: Install a Web Server (Apache)#

CakePHP requires a web server. We'll use Apache, which is well-supported and easy to configure.

sudo apt install apache2 -y

After installation, start the Apache service and enable it to start automatically on system boot.

sudo systemctl start apache2
sudo systemctl enable apache2

You can verify that Apache is running by visiting your server's IP address in a web browser (e.g., http://your_server_ip). You should see the default Ubuntu Apache welcome page.

Step 3: Install PHP and Required Extensions#

CakePHP 5.x requires PHP 8.1 or later. Ubuntu 24.04's default repositories include a compatible version. We need to install PHP along with the essential extensions CakePHP depends on.

sudo apt install php php-cli php-common php-mysql php-mbstring php-xml php-curl php-intl php-zip -y

To verify the PHP installation and check the version:

php -v

You should see output confirming PHP 8.3 or similar.

Step 4: Install a Database (MariaDB)#

While CakePHP supports various databases, we'll use MariaDB, a popular drop-in replacement for MySQL.

sudo apt install mariadb-server mariadb-client -y

Secure your MariaDB installation by running the security script. It will prompt you to set a root password and make some security-related changes. It's safe to answer Y (yes) to all prompts.

sudo mysql_secure_installation

Step 5: Install Composer (PHP Dependency Manager)#

Composer is the standard tool for managing dependencies in PHP projects, and it's the recommended way to install CakePHP.

Download the Composer installer.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

Verify the installer's integrity. Visit getcomposer.org to get the latest hash.

# Replace the HASH with the latest one from the Composer page
php -r "if (hash_file('sha384', 'composer-setup.php') === 'HASH_HERE') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Run the installer to install Composer globally.

sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Remove the installer script.
```
php -r "unlink('composer-setup.php');"
```
Verify the installation:
```
composer --version
```

Step 6: Create a New CakePHP Project#

Now, we'll use Composer to create a new CakePHP project. Let's create it in the /var/www/ directory, which is the standard location for web applications on Ubuntu.

Navigate to the web directory:
```
cd /var/www/
```
Use Composer's create-project command to set up the new CakePHP application. We'll call our project my_cakephp_app.
```
sudo composer create-project --prefer-dist cakephp/app:~5.0 my_cakephp_app
```
This command will download the latest CakePHP 5.x release and all its dependencies. This may take a few minutes.

Step 7: Configure Apache for CakePHP#

We need to create an Apache Virtual Host file to serve our CakePHP application.

Create a new configuration file for your site. You can name it after your domain or project (e.g., my_cakephp_app.conf).
```
sudo nano /etc/apache2/sites-available/my_cakephp_app.conf
```

Paste the following configuration into the file. Replace your_server_domain_or_IP with your actual domain name or server IP address. The DocumentRoot must point to the webroot directory inside your CakePHP project.

<VirtualHost *:80>
    ServerName your_server_domain_or_IP
    DocumentRoot /var/www/my_cakephp_app/webroot
 
    <Directory /var/www/my_cakephp_app/webroot>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
 
    ErrorLog ${APACHE_LOG_DIR}/my_cakephp_app_error.log
    CustomLog ${APACHE_LOG_DIR}/my_cakephp_app_access.log combined
</VirtualHost>

Save and close the file (in nano, press Ctrl+X, then Y, then Enter).

Disable the default Apache site and enable your new CakePHP site.

sudo a2dissite 000-default.conf
sudo a2ensite my_cakephp_app.conf

Enable the Apache rewrite module, which is essential for CakePHP's pretty URLs.
```
sudo a2enmod rewrite
```
Test the Apache configuration for syntax errors:
```
sudo apache2ctl configtest
```
If it returns Syntax OK, restart Apache to apply the changes.
```
sudo systemctl restart apache2
```

Step 8: Set File Permissions#

CakePHP needs specific write permissions on the logs and tmp directories.

Change the ownership of your project directory to the web server user (www-data on Ubuntu).
```
sudo chown -R www-data:www-data /var/www/my_cakephp_app
```

Set the correct permissions for the tmp and logs directories.

sudo chmod -R 755 /var/www/my_cakephp_app
sudo chmod -R 775 /var/www/my_cakephp_app/tmp
sudo chmod -R 775 /var/www/my_cakephp_app/logs

Step 9: Configure the Database (Optional)#

If your application will use a database, you need to create one and configure CakePHP to connect to it.

Create a database and a dedicated user for your CakePHP app (replace password with a strong one):

CREATE DATABASE cakephp_db;
CREATE USER 'cakephp_user'@'localhost' IDENTIFIED BY 'your_strong_password_here';
GRANT ALL PRIVILEGES ON cakephp_db.* TO 'cakephp_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Configure CakePHP to use this database. Open the config/app_local.php file in your project.
```
sudo nano /var/www/my_cakephp_app/config/app_local.php
```

Find the Datasources section and update the default connection array with your database details:

'default' => [
    'host' => 'localhost',
    'username' => 'cakephp_user',
    'password' => 'your_strong_password_here',
    'database' => 'cakephp_db',
    // ... other settings remain the same
],

Save and close the file.

Step 10: Test the Installation#

Open your web browser and navigate to your server's IP address or domain name (e.g., http://your_server_ip).

You should see the default CakePHP welcome page. The page will indicate if there are any issues with your installation, such as missing extensions or incorrect file permissions. If you see the welcome page, congratulations! CakePHP has been successfully installed on Ubuntu 24.04.

Troubleshooting Common Issues#

Error: "The requested URL / was not found on this server."
- Solution: Double-check your Apache Virtual Host configuration. Ensure the DocumentRoot points to /var/www/my_cakephp_app/webroot and that the site is enabled (a2ensite). Also, confirm the rewrite module is enabled.
Error: "CakePHP is NOT able to connect to the database."
- Solution: Verify the database credentials in config/app_local.php. Ensure the database, user, and password are correct and that the user has the necessary privileges.
Error: "logs and tmp directories must be writable"
- Solution: Re-run the permission commands from Step 8. Ensure the user www-data owns the directories and the permissions are set to 775.
Composer Command Not Found
- Solution: Ensure you installed Composer globally in /usr/local/bin and that this directory is in your PATH. You can also try running it with php /usr/local/bin/composer.

Conclusion#

You have successfully installed CakePHP on Ubuntu 24.04. Your environment is now ready for development, complete with a web server, PHP, a database, and the CakePHP framework itself. From here, you can start building your application by defining models, controllers, and views according to the CakePHP conventions. Explore the official CakePHP documentation to learn more about its powerful features.