How to Install SuiteCRM 8 on Ubuntu 24.04 LTS with Apache and MariaDB
Install SuiteCRM 8 on Ubuntu 24.04 LTS with Apache, MariaDB and PHP 8.3, then configure the scheduler cron job and the background worker.
SuiteCRM is an open-source customer relationship management application that began as a fork of the last SugarCRM Community Edition. This guide installs the current SuiteCRM 8 release (8.10 at the time of writing) on Ubuntu 24.04 LTS with Apache, MariaDB and PHP, using the project's command-line installer, and then sets up the scheduler cron job and the background worker that SuiteCRM 8.10 needs.
Ubuntu 24.04 is used on purpose. SuiteCRM's compatibility matrix for 8.10 lists PHP 8.2, 8.3 and 8.4. Ubuntu 26.04 LTS ships PHP 8.5, which is not on that list yet, while Ubuntu 24.04 provides PHP 8.3 and MariaDB 10.11, both supported. Ubuntu 16.04 and its PHP 7.0 are long out of support.
Requirements
- A server running Ubuntu 24.04 LTS with at least 2 GB of RAM.
- A user with
sudorights (the examples usedeploy). - A domain or subdomain pointing to the server. The examples use
crm.example.com.
SuiteCRM 8.10 supports Apache 2.4, MariaDB 10.6, 10.11, 11.4 and 11.8, and MySQL 8.0 and 8.4.
Install Apache, MariaDB and PHP
sudo apt update
sudo apt install apache2 mariadb-server libapache2-mod-php php-cli php-curl php-intl php-gd php-mbstring php-mysql php-soap php-xml php-zip php-imap php-ldap unzip
This covers the PHP modules the SuiteCRM web server guide lists: cli, curl, intl, gd, mbstring, mysqli, pdo_mysql, soap, xml and zip; JSON and OpenSSL support are built into Ubuntu's PHP. imap (for inbound email) and ldap are optional, and you can leave those two packages out if you do not need them.
Confirm the PHP version:
php -v
Adjust PHP settings
The installer's system check warns about low upload and memory limits. Raise them in both the Apache and the command-line configuration, /etc/php/8.3/apache2/php.ini and /etc/php/8.3/cli/php.ini:
memory_limit = 256M
upload_max_filesize = 20M
post_max_size = 20M
SuiteCRM's documentation also asks that notices and warnings are not treated as errors:
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_NOTICE & ~E_WARNING
Create the database user
On Ubuntu the MariaDB root account is authenticated through the system, so open the shell with sudo:
sudo mariadb
Create a database and a user that owns it. The installer connects over TCP when you give it 127.0.0.1 as the host, so the account is created for both forms of the local address:
CREATE DATABASE suitecrm CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'suitecrm'@'localhost' IDENTIFIED BY 'change-this-db-password';
CREATE USER 'suitecrm'@'127.0.0.1' IDENTIFIED BY 'change-this-db-password';
GRANT ALL PRIVILEGES ON suitecrm.* TO 'suitecrm'@'localhost';
GRANT ALL PRIVILEGES ON suitecrm.* TO 'suitecrm'@'127.0.0.1';
EXIT;
Download SuiteCRM
Get the pre-built package from the official download page, suitecrm.com/download. At the time of writing the SuiteCRM 8 package is 8.10.2; if a newer one is listed, use its link instead.
cd /tmp
wget https://suitecrm.com/download/168/suite810/569258/suitecrm-8-10-2.zip
sudo mkdir /var/www/suitecrm
sudo unzip -q suitecrm-8-10-2.zip -d /var/www/suitecrm
Check that /var/www/suitecrm now contains bin, public and vendor directly. Then set the ownership and permissions the installation guide specifies, from inside the SuiteCRM directory:
cd /var/www/suitecrm
sudo find . -type d -not -perm 2755 -exec chmod 2755 {} \;
sudo find . -type f -not -perm 0644 -exec chmod 0644 {} \;
sudo find . ! -user www-data -exec chown www-data:www-data {} \;
sudo chmod +x bin/console
Configure Apache
SuiteCRM 8 must be served from its public directory, not from the application root; otherwise files outside public could be exposed. It also needs mod_rewrite and AllowOverride All, without which API calls return 404 errors.
Create /etc/apache2/sites-available/suitecrm.conf:
<VirtualHost *:80>
ServerName crm.example.com
DocumentRoot /var/www/suitecrm/public
<Directory /var/www/suitecrm/public>
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/suitecrm_error.log
CustomLog ${APACHE_LOG_DIR}/suitecrm_access.log combined
</VirtualHost>
Enable the module and the site, and reload Apache:
sudo a2enmod rewrite
sudo a2ensite suitecrm
sudo a2dissite 000-default
sudo apache2ctl configtest
sudo systemctl restart apache2
Add HTTPS before installing
A CRM carries logins and customer data, so serve it over TLS. The installer stores the site URL, so it is easiest to obtain the certificate first. With Let's Encrypt:
sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d crm.example.com
Run the installer
Run the command-line installer as the web server user so that the files it generates have the right owner. Called without options, it asks for each value in turn, which keeps passwords out of your shell history:
cd /var/www/suitecrm
sudo -u www-data ./bin/console suitecrm:app:install
The same values can be passed as options, which is useful for automated deployments:
sudo -u www-data ./bin/console suitecrm:app:install -u "admin" -p "change-this-admin-password" -U "suitecrm" -P "change-this-db-password" -H "127.0.0.1" -N "suitecrm" -S "https://crm.example.com/" -d "no"
| Option | Meaning |
|---|---|
-u, -p | User name and password of the SuiteCRM administrator to create |
-U, -P | Database user and password |
-H | Database host. Use 127.0.0.1 if localhost causes socket connection errors |
-N | Database name |
-S | The URL under which SuiteCRM is reached |
-d | yes to load demo data, no for an empty system |
./bin/console suitecrm:app:install --help lists further options, such as the database port. When the installer has finished, apply the permissions once more as the documentation instructs:
sudo find . -type d -not -perm 2755 -exec chmod 2755 {} \;
sudo find . -type f -not -perm 0644 -exec chmod 0644 {} \;
sudo find . ! -user www-data -exec chown www-data:www-data {} \;
sudo chmod +x bin/console
If you prefer a browser, open https://crm.example.com/ instead of running the command: the web installer shows the system check and asks for the same values.
Verify
Open https://crm.example.com/ and log in with the administrator account. If the login page loads but requests fail, check two files the installer writes:
public/legacy/config.php:site_urlmust be the address you use in the browser.public/legacy/.htaccess: with the virtual host pointing atpublic, the line must readRewriteBase /legacy.
Set up the scheduler cron job
Workflows, inbound email checks and scheduled reports only run if cron calls the scheduler. Edit the crontab of the web server user:
sudo crontab -e -u www-data
Add this line:
* * * * * /usr/bin/php /var/www/suitecrm/bin/console schedulers:run > /dev/null 2>&1
The user that runs the job must be listed in allowed_cron_users in the configuration; the installer normally adds the web server user for you. Do not run the scheduler as root. Admin → Schedulers shows when the job last ran and as which user.
Run the background worker
From SuiteCRM 8.10 on, background tasks are processed by a Symfony Messenger worker. Without it they stay in the "Pending" state. Create /etc/systemd/system/suitecrm-messenger.service:
[Unit]
Description=SuiteCRM Messenger Worker
After=network.target
[Service]
Type=simple
User=www-data
Group=www-data
ExecStart=/usr/bin/php /var/www/suitecrm/bin/console messenger:consume internal-async --time-limit=3600 --memory-limit=256M
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now suitecrm-messenger
systemctl status suitecrm-messenger
The worker exits after an hour by design and systemd starts it again, which keeps memory use in check.
Maintenance
- Back up the database (
sudo mariadb-dump suitecrm > suitecrm.sql) and the/var/www/suitecrmdirectory together, and always before an upgrade. - Application logs are written below
/var/www/suitecrm/logs, and the legacy log issuitecrm.log. Apache errors are in/var/log/apache2/suitecrm_error.log. - Upgrades are done with SuiteCRM's own upgrade packages, not with
apt. Follow the upgrade instructions in the SuiteCRM 8 administration guide for each release, and check the compatibility matrix before you change the PHP or MariaDB version underneath it.
Frequently asked questions
Should I install SuiteCRM 7 or SuiteCRM 8?
Both are offered on the download page. SuiteCRM 8 has the newer interface and is where new development happens; the project describes 7.15 as the choice for people upgrading from earlier 7.x releases and those who want maximum stability. For a new installation, start with 8 unless you depend on a module that only exists for 7.
Can I run it on Ubuntu 26.04?
Not with the distribution's PHP, as long as PHP 8.5 is missing from SuiteCRM's compatibility matrix. Use Ubuntu 24.04, or wait until a SuiteCRM release lists PHP 8.5 as supported. Running a CRM on an unsupported PHP version tends to surface as errors in less-used modules rather than at install time.
Why does the installer want 127.0.0.1 instead of localhost?
With localhost, the PHP database driver tries the MariaDB Unix socket, and SuiteCRM's documentation notes this can fail. An IP address forces a TCP connection to the same local server. MariaDB on Ubuntu listens only on the loopback address by default, so this does not expose the database.
Do I need Nginx or PHP-FPM?
No. Apache 2.4 is the web server in SuiteCRM's compatibility matrix and the one its installation guide documents, including the .htaccess rules the application relies on.