How to Install SuiteCRM 8.8 on Ubuntu 24.04

This beginner-friendly guide explains how to manually install and configure SuiteCRM 8.8 on an Ubuntu 24.04 LTS server.

The commands in this article follow the same installation process used by the provided SuiteCRM Ansible deployment.

Step 1: Connect to the Ubuntu Server

Open PowerShell, Windows Terminal, PuTTY, or another SSH client. Connect to your Ubuntu server:

ssh username@SERVER-IP

Replace username with your Ubuntu username and SERVER-IP with your server's IP address.

Example:

ssh ubuntu@203.0.113.10

If you are already logged into the Ubuntu server, continue to the next step.

Step 2: Check the Ubuntu Version

Verify that the server is running Ubuntu 24.04:

lsb_release -a

The server should report Ubuntu 24.04 LTS.

Step 3: Update Ubuntu

Update the package list:

sudo apt update

Upgrade the installed packages:

sudo apt upgrade -y

Step 4: Install Apache, MySQL and Required Packages

The SuiteCRM deployment requires Apache, MySQL, PHP and several supporting packages.

Install the required packages:

sudo apt install -y apache2 mysql-server unzip wget curl python3-pymysql libapache2-mod-php8.3 php8.3 php8.3-cli php8.3-common php8.3-curl php8.3-mysql php8.3-xml php8.3-mbstring php8.3-gd php8.3-intl php8.3-bcmath php8.3-soap php8.3-zip php8.3-imap

The installation may take several minutes.

Step 5: Verify PHP 8.3

Check the installed PHP version:

php -v

The output should show PHP 8.3.

Check the installed PHP modules:

php -m

Step 6: Enable PHP 8.3 in Apache

Enable the PHP 8.3 Apache module:

sudo a2enmod php8.3

Step 7: Disable PHP 8.4 if Present

The SuiteCRM deployment is configured to use PHP 8.3. If PHP 8.4 is enabled in Apache, disable it:

sudo a2dismod php8.4

If you receive a message saying that PHP 8.4 is not enabled, you can continue.

Step 8: Enable Apache Rewrite

SuiteCRM requires Apache URL rewriting. Enable the rewrite module:

sudo a2enmod rewrite

Step 9: Start and Enable Apache

Start Apache:

sudo systemctl start apache2

Enable Apache so it starts automatically after a reboot:

sudo systemctl enable apache2

Check the service:

sudo systemctl status apache2 --no-pager

Look for:

Active: active (running)

Step 10: Start and Enable MySQL

Start MySQL:

sudo systemctl start mysql

Enable MySQL at boot:

sudo systemctl enable mysql

Check MySQL:

sudo systemctl status mysql --no-pager

Step 11: Configure PHP

The supplied deployment configures PHP using:

• Memory limit: 256M
• Upload maximum size: 50M
• POST maximum size: 50M
• Maximum execution time: 300 seconds
• Custom error reporting

Open the PHP 8.3 Apache configuration:

sudo nano /etc/php/8.3/apache2/php.ini

Find the following settings and make sure they contain these values:

memory_limit = 256M
upload_max_filesize = 50M
post_max_size = 50M
max_execution_time = 300
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_NOTICE & ~E_WARNING

Save the file:

• Press Ctrl + O
• Press Enter
• Press Ctrl + X

Step 12: Restart Apache

Apply the PHP configuration:

sudo systemctl restart apache2

Step 13: Create the SuiteCRM Database

The deployment uses the following database information:

• Database: suitecrm_db
• Username: suitecrm_user
• Password: StrongPasswordHere!
• Host: localhost

Open MySQL:

sudo mysql

Create the SuiteCRM database:

CREATE DATABASE suitecrm_db CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

Create the SuiteCRM database user:

CREATE USER 'suitecrm_user'@'localhost' IDENTIFIED BY 'StrongPasswordHere!';

Give the user full access to the SuiteCRM database:

GRANT ALL PRIVILEGES ON suitecrm_db.* TO 'suitecrm_user'@'localhost';

Apply the privileges:

FLUSH PRIVILEGES;

Exit MySQL:

EXIT;

Step 14: Test the SuiteCRM Database User

Test the database credentials:

mysql -u suitecrm_user -p

When prompted for the password, enter:

StrongPasswordHere!

If the login succeeds, the database user is working correctly.

Exit MySQL:

EXIT;

Step 15: Create the SuiteCRM Installation Directory

The deployment installs SuiteCRM in:

/var/www/html/suitecrm

Create the directory:

sudo mkdir -p /var/www/html/suitecrm

Set the owner:

sudo chown www-data:www-data /var/www/html/suitecrm

Set the permissions:

sudo chmod 755 /var/www/html/suitecrm

Step 16: Download SuiteCRM 8.8

The deployment downloads SuiteCRM 8.8 from the SuiteCRM download server.

Download the archive:

wget -O /tmp/suitecrm-8-8-0.zip "https://suitecrm.com/download/165/suite88/565090/suitecrm-8-8-0.zip"

Check that the archive exists:

ls -lh /tmp/suitecrm-8-8-0.zip

Step 17: Create a Temporary Extraction Directory

Create the directory used to extract SuiteCRM:

sudo mkdir -p /tmp/suitecrm-extract

Step 18: Extract SuiteCRM

Extract the SuiteCRM archive:

sudo unzip /tmp/suitecrm-8-8-0.zip -d /tmp/suitecrm-extract

Check the extracted files:

find /tmp/suitecrm-extract -maxdepth 3 -type d -name public

The SuiteCRM archive should contain a public directory.

Step 19: Copy SuiteCRM Files

The supplied Ansible deployment finds the SuiteCRM application root and copies its contents into:

/var/www/html/suitecrm

If the extracted application root is directly inside /tmp/suitecrm-extract, use:

sudo cp -a /tmp/suitecrm-extract/. /var/www/html/suitecrm/

Check the installation directory:

ls -lah /var/www/html/suitecrm

Make sure the SuiteCRM application contains directories and files such as bin, config, public, and other application files.

Step 20: Set SuiteCRM File Permissions

Set directory permissions:

sudo find /var/www/html/suitecrm -type d -exec chmod 2755 {} \;

Set file permissions:

sudo find /var/www/html/suitecrm -type f -exec chmod 0644 {} \;

Set ownership:

sudo chown -R www-data:www-data /var/www/html/suitecrm

Make the SuiteCRM console executable:

sudo chmod +x /var/www/html/suitecrm/bin/console

Step 21: Set SuiteCRM Writable Directories

SuiteCRM requires several directories to be writable. Set the required permissions:

sudo chmod -R 2775 /var/www/html/suitecrm/cache
sudo chmod -R 2775 /var/www/html/suitecrm/custom
sudo chmod -R 2775 /var/www/html/suitecrm/modules
sudo chmod -R 2775 /var/www/html/suitecrm/themes
sudo chmod -R 2775 /var/www/html/suitecrm/data
sudo chmod -R 2775 /var/www/html/suitecrm/upload

Ensure they belong to Apache:

sudo chown -R www-data:www-data /var/www/html/suitecrm/cache
sudo chown -R www-data:www-data /var/www/html/suitecrm/custom
sudo chown -R www-data:www-data /var/www/html/suitecrm/modules
sudo chown -R www-data:www-data /var/www/html/suitecrm/themes
sudo chown -R www-data:www-data /var/www/html/suitecrm/data
sudo chown -R www-data:www-data /var/www/html/suitecrm/upload

Step 22: Create the Apache Virtual Host

Create the SuiteCRM Apache configuration:

sudo nano /etc/apache2/sites-available/suitecrm.conf

Paste the following:

<VirtualHost *:80>
    ServerName YOUR_SERVER_IP

    DocumentRoot /var/www/html/suitecrm/public

    <Directory /var/www/html/suitecrm/public>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/suitecrm_error.log
    CustomLog ${APACHE_LOG_DIR}/suitecrm_access.log combined
</VirtualHost>

Replace YOUR_SERVER_IP with the IP address of your Ubuntu server.

For example:

ServerName 203.0.113.10

Save the file:

• Press Ctrl + O
• Press Enter
• Press Ctrl + X

Step 23: Enable the SuiteCRM Apache Site

Enable the SuiteCRM site:

sudo a2ensite suitecrm.conf

Step 24: Disable the Default Apache Site

Disable the default Apache website:

sudo a2dissite 000-default.conf

Step 25: Test Apache Configuration

Before restarting Apache, always test the configuration:

sudo apache2ctl configtest

A successful configuration should report:

Syntax OK

Step 26: Restart Apache

Restart Apache:

sudo systemctl restart apache2

Check Apache:

sudo systemctl status apache2 --no-pager

Step 27: Configure the Firewall

If UFW is enabled, allow HTTP traffic on port 80:

sudo ufw allow 80/tcp

Allow HTTPS traffic on port 443:

sudo ufw allow 443/tcp

Check the firewall:

sudo ufw status

Step 28: Create the SuiteCRM Scheduler Cron Job

SuiteCRM uses a scheduler command that should run regularly. The supplied deployment creates a cron job that runs every minute.

Create the cron job for the www-data user:

sudo crontab -u www-data -e

Add this line:

* * * * * cd /var/www/html/suitecrm && php bin/console schedulers:run >> /dev/null 2>&1

Save and exit the editor.

Step 29: Check the Cron Job

Verify that the scheduler was created:

sudo crontab -u www-data -l

You should see:

* * * * * cd /var/www/html/suitecrm && php bin/console schedulers:run >> /dev/null 2>&1

Step 30: Check the SuiteCRM Files

Verify the SuiteCRM installation:

ls -lah /var/www/html/suitecrm

Check the public directory:

ls -lah /var/www/html/suitecrm/public

The Apache document root should point to:

/var/www/html/suitecrm/public

Step 31: Check the SuiteCRM Console

Verify that the SuiteCRM console exists:

ls -l /var/www/html/suitecrm/bin/console

Test it:

cd /var/www/html/suitecrm
sudo -u www-data php bin/console --help

Step 32: Find Your Server IP Address

Run:

hostname -I

Copy the public IP address of your server.

Step 33: Open SuiteCRM in Your Browser

Open a web browser on your computer and enter:

http://YOUR_SERVER_IP

For example:

http://203.0.113.10

The SuiteCRM installer should appear.

Step 34: Open the SuiteCRM Installer Directly

The supplied Ansible deployment displays the following installer URL:

http://YOUR_SERVER_IP/install.php

For example:

http://203.0.113.10/install.php

Step 35: Enter the Database Information

During the SuiteCRM web installation, use the database information created earlier.

Continue through the SuiteCRM installation wizard and create the SuiteCRM administrator account when requested.

Step 36: Check Apache Logs

If SuiteCRM does not load, check the SuiteCRM Apache error log:

sudo tail -n 100 /var/log/apache2/suitecrm_error.log

Check the access log:

sudo tail -n 100 /var/log/apache2/suitecrm_access.log

Step 37: Check Apache Configuration

Test Apache:

sudo apache2ctl configtest

Check the enabled SuiteCRM site:

ls -l /etc/apache2/sites-enabled/

Check the SuiteCRM configuration:

sudo cat /etc/apache2/sites-available/suitecrm.conf

Step 38: Check PHP Modules

Check that the required PHP extensions are available:

php -m

The deployment installs extensions including:

• curl
• mysql
• xml
• mbstring
• gd
• intl
• bcmath
• soap
• zip
• imap

Step 39: Check Apache and MySQL Services

Check Apache:

sudo systemctl status apache2 --no-pager

Check MySQL:

sudo systemctl status mysql --no-pager

Both services should report:

Active: active (running)

Step 40: Check Port 80

Apache should listen on HTTP port 80. Run:

sudo ss -tulpn | grep :80

You should see Apache listening on port 80.

Step 41: Test SuiteCRM Locally

Test the web server directly from the Ubuntu server:

curl -I http://localhost

You can also test the installer:

curl -I http://localhost/install.php

Step 42: Troubleshooting a Blank or Error Page

If SuiteCRM displays a blank page or server error, first check Apache:

sudo systemctl status apache2 --no-pager -l

Then check the SuiteCRM Apache error log:

sudo tail -n 100 /var/log/apache2/suitecrm_error.log

Check the PHP version:

php -v

Make sure PHP 8.3 is being used.

Step 43: Troubleshooting Permission Errors

If SuiteCRM reports that files or directories are not writable, reset the ownership:

sudo chown -R www-data:www-data /var/www/html/suitecrm

Reset the writable directories:

sudo chmod -R 2775 /var/www/html/suitecrm/cache
sudo chmod -R 2775 /var/www/html/suitecrm/custom
sudo chmod -R 2775 /var/www/html/suitecrm/modules
sudo chmod -R 2775 /var/www/html/suitecrm/themes
sudo chmod -R 2775 /var/www/html/suitecrm/data
sudo chmod -R 2775 /var/www/html/suitecrm/upload

Step 44: Troubleshooting MySQL

Check MySQL:

sudo systemctl status mysql --no-pager -l

Test the SuiteCRM database:

mysql -u suitecrm_user -p suitecrm_db

Enter:

StrongPasswordHere!

If the login succeeds, the database connection is working.

Exit MySQL:

EXIT;

Step 45: Check the SuiteCRM Scheduler

Check the cron job:

sudo crontab -u www-data -l

You can also manually test the scheduler:

cd /var/www/html/suitecrm
sudo -u www-data php bin/console schedulers:run

Step 46: Final Verification

Run these commands to verify the installation:

php -v

sudo systemctl status apache2 --no-pager

sudo systemctl status mysql --no-pager

sudo apache2ctl configtest

sudo ss -tulpn | grep :80

ls -lah /var/www/html/suitecrm

ls -lah /var/www/html/suitecrm/public

sudo crontab -u www-data -l

Step 47: Access SuiteCRM

http://YOUR_SERVER_IP

http://YOUR_SERVER_IP/install.php

Installation Complete

Configuration Summary

Quick Access

Important Security Notice

Important Note About the Supplied Project

The supplied SuiteCRM playbook configures Apache directly inside suitecrm.yml. It creates the virtual host on port 80 and uses /var/www/html/suitecrm/public as the document root.

The project also contains a separate templates/suitecrm.conf.j2 file containing an Apache configuration for port 8080. That template is not used by the supplied playbook's virtual-host task, so this manual guide follows the actual playbook configuration and uses port 80.

This knowledgebase article is based on the supplied SuiteCRM Ansible project, including SuiteCRM 8.8, Apache, MySQL, PHP 8.3, the configured PHP extensions, the SuiteCRM database, the Apache virtual host, UFW rules, and the SuiteCRM scheduler.