How to Install SuiteCRM 8 on Ubuntu 24.04 VPS: Enterprise Open-Source CRM
SuiteCRM 8 is the most fully-featured open-source CRM available today -- a Symfony + Angular rewrite of the original SugarCRM Community Edition that powers sales, marketing, and customer service teams at tens of thousands of organisations worldwide. This guide walks you through installing SuiteCRM 8 on an Ubuntu 24.04 VPS from a fresh SSH session, configuring Nginx or Apache with TLS, wiring up the cron scheduler, and hardening the deployment for production use.
Own your customer data. SuiteCRM is licensed under AGPL v3 -- you host it, you control it, and no vendor can raise your per-seat price. Deploy on our CloudCore Professional VPS and replace Salesforce, HubSpot, or Zoho at a flat monthly cost.
Table of Contents
What is SuiteCRM?
SuiteCRM is a free and open-source customer relationship management platform originally forked from SugarCRM Community Edition in 2013 by British consultancy SalesAgility. When SugarCRM discontinued its open-source community edition, SuiteCRM picked up the torch and has been actively maintained and extended ever since. The current generation, SuiteCRM 8, is a ground-up modernisation that keeps the battle-tested business logic of the v7 codebase while replacing the ageing Smarty-template frontend with a Symfony 6 backend and an Angular single-page frontend.
SuiteCRM covers the full sales, marketing, and service lifecycle. On the sales side, it manages Leads, Contacts, Accounts, Opportunities, and Quotes, with a full sales pipeline, forecasting, and reporting suite. On the marketing side, it ships a Campaigns module supporting email blasts, newsletters, A/B testing, and bounce tracking, plus tracked web-to-lead forms. On the service side, Cases, Bugs, and a Knowledge Base plug directly into a self-service customer portal. Underpinning all of this is Studio -- a point-and-click module builder that lets non-developers add custom fields, relationships, and modules without touching PHP -- and a Workflow engine that fires automated actions on record changes.
SuiteCRM competes directly with Salesforce Sales Cloud, HubSpot CRM, Zoho CRM, and Microsoft Dynamics 365. Unlike those SaaS products, SuiteCRM has no per-user fees, no API call caps, no storage tiers, and no data-export restrictions. You install it on your own VPS, and it is yours forever.
Why Self-Host SuiteCRM on Your VPS?
Running SuiteCRM on your own infrastructure rather than paying per seat to a hosted CRM vendor delivers concrete advantages:
- No per-seat licensing -- Add 5 users or 500 at the same flat VPS cost. Salesforce Sales Cloud starts at USD 25/user/month; a 50-person team pays USD 15,000/year. The same 50 users on SuiteCRM cost the price of one VPS.
- Data sovereignty -- Your customer database, email history, deal pipeline, and call recordings live on a server you control. GDPR, HIPAA, and SOC 2 scoping become trivial when there is no third-party processor in the loop.
- Unlimited customisation -- Full source code access means you can modify any module, add any field, build any integration, or fork the whole platform. Studio covers 80% of customisation without code; the other 20% is pure PHP.
- No API throttling -- Hosted CRMs meter your API calls. Self-hosted SuiteCRM answers as many REST/v8 API requests per second as your VPS can serve, ideal for heavy integrations with marketing automation or e-commerce platforms.
- AGPL v3 licensing -- You can run it commercially, modify it, redistribute modifications, and sell services around it. The only requirement is that if you offer SuiteCRM as a hosted service, you must make your modifications available to your users.
- Mature ecosystem -- SuiteCRM has been in production for over a decade. Hundreds of community and commercial modules exist for everything from DocuSign integration to Asterisk telephony.
Cost Comparison: SuiteCRM vs. Hosted CRM
| Scenario (50 users) | Salesforce Sales Cloud | HubSpot Sales Pro | Zoho CRM Enterprise | Self-Hosted SuiteCRM |
|---|---|---|---|---|
| Monthly cost | USD 1,250+ | USD 4,500+ | USD 2,000+ | EUR 19.99 (VPS only) |
| Per-user fees | Yes | Yes | Yes | None |
| API call limits | 100K/day (base) | 500K/day | 250K/day | None |
| Storage limits | 10 GB + USD/GB | Metered | Metered | Disk size |
| Custom modules | Paid tier | Paid tier | Paid tier | Unlimited |
| Source code access | No | No | No | Yes (AGPL) |
| Data export | CSV only | CSV only | CSV only | Full SQL dump |
Prerequisites
Before you begin, make sure you have:
- A VPS running Ubuntu 24.04 LTS with root or sudo access
- SSH access to the server
- A domain name (e.g.
crm.yourcompany.com) with an A record pointing to the VPS IP - At least 2 GB of RAM (4 GB+ strongly recommended for more than a handful of concurrent users)
- At least 20 GB of free disk space -- SuiteCRM itself is small, but the database, email cache, and upload directory grow over time
- An SMTP relay (Gmail, SendGrid, Amazon SES, or your own Postfix) for outbound email
Recommended Plan: CloudCore Professional>
SuiteCRM 8's Symfony + Angular stack is heavier than v7 and rewards CPU and RAM. For teams up to 50 users we recommend the CloudCore Professional plan:>
- 6 vCPU cores
- 12 GB RAM
- 100 GB NVMe SSD
- Unmetered bandwidth
- EUR 19.99/month>
This comfortably hosts SuiteCRM, MariaDB, Redis, and a reverse-proxy with headroom for frontend caching and batch campaign sends.
Connect to your VPS via SSH to begin:
ssh root@your-server-ipStep 1: Update the System and Create a Deploy User
Start with a fully patched system and a non-root user that owns the SuiteCRM files.
sudo apt update && sudo apt upgrade -yCreate a dedicated deploy user:
sudo adduser --disabled-password --gecos "" suitecrm
sudo usermod -aG www-data suitecrmInstall a handful of common utilities you will use throughout the guide:
sudo apt install -y curl wget unzip git software-properties-common ca-certificates gnupg lsb-releaseIf your kernel was updated during the upgrade, reboot before continuing:
sudo rebootReconnect once the VPS is back online.
Step 2: Install PHP 8.2 and Required Extensions
SuiteCRM 8.6+ supports PHP 8.1 and 8.2. We recommend PHP 8.2 for better performance and longer security support. Ubuntu 24.04 ships PHP 8.3 by default, which is not yet officially supported by SuiteCRM, so we will add Ondřej Surý's PPA to get a supported version.
Add the PHP PPA:
sudo add-apt-repository -y ppa:ondrej/php
sudo apt updateInstall PHP 8.2 with every extension SuiteCRM requires:
sudo apt install -y php8.2 php8.2-fpm php8.2-cli \
php8.2-bcmath php8.2-curl php8.2-gd php8.2-imap php8.2-intl \
php8.2-ldap php8.2-mbstring php8.2-mysql php8.2-soap \
php8.2-xml php8.2-zip php8.2-opcache php8.2-readlineExpected extensions (verify after install with php -m):
- bcmath -- arbitrary-precision maths for money fields
- curl -- outbound HTTP for integrations and updates
- gd -- image resizing for user avatars and attachments
- imap -- inbound email polling for Cases and the Inbound Email module
- intl -- locale-aware date and number formatting
- ldap -- Active Directory / OpenLDAP authentication (optional but often needed)
- mbstring -- multi-byte string handling for i18n
- mysqli and pdo_mysql -- database driver (both shipped by
php8.2-mysql) - openssl -- TLS, password hashing (bundled in PHP core)
- simplexml, xml, soap -- SOAP API and XML import/export (bundled in
php8.2-xmlandphp8.2-soap) - zip -- module and language pack installers
/etc/php/8.2/fpm/php.ini:sudo nano /etc/php/8.2/fpm/php.iniSet these values (use Ctrl+W in nano to search):
memory_limit = 512M
upload_max_filesize = 50M
post_max_size = 50M
max_execution_time = 300
max_input_time = 300
max_input_vars = 5000
date.timezone = UTC
session.gc_maxlifetime = 28800The most common install failure is a low memory_limit. SuiteCRM 8's Symfony bootstrap easily uses 256 MB during installation and cache warming; 512 MB gives comfortable headroom.
Restart PHP-FPM:
sudo systemctl restart php8.2-fpm
sudo systemctl enable php8.2-fpmVerify:
php -v
php -m | sortExpected output (abbreviated):
PHP 8.2.20 (cli) (built: ...)
bcmath
curl
gd
imap
intl
ldap
mbstring
mysqli
mysqlnd
openssl
pdo_mysql
...Step 3: Install MariaDB and Create the Database
SuiteCRM supports MySQL 8.0+ and MariaDB 10.6+. We recommend MariaDB -- it is the default on most Linux distros, has slightly better performance on SuiteCRM's workload, and is fully drop-in compatible. See our in-depth guide How to Install MariaDB on Ubuntu 24.04 for advanced tuning.
Install MariaDB:
sudo apt install -y mariadb-server mariadb-clientRun the secure installation wizard:
sudo mysql_secure_installationAnswer the prompts:
- Switch to unix_socket authentication? --
n(we want a password) - Set root password? --
Y, then set a strong password - Remove anonymous users? --
Y - Disallow root login remotely? --
Y - Remove test database? --
Y - Reload privilege tables? --
Y
sudo mysql -u root -pIn the MariaDB prompt, run:
CREATE DATABASE suitecrm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'suitecrm'@'localhost' IDENTIFIED BY 'ChangeThisStrongPassword!';
GRANT ALL PRIVILEGES ON suitecrm.* TO 'suitecrm'@'localhost';
FLUSH PRIVILEGES;
EXIT;Replace ChangeThisStrongPassword! with a real long random password -- store it in your password manager, you will need it in Step 6.
Verify the login works:
mysql -u suitecrm -p suitecrm -e "SELECT VERSION();"Expected output:
+-----------------+
| VERSION() |
+-----------------+
| 10.11.8-MariaDB |
+-----------------+Step 4: Install Composer 2 and Node.js 18
SuiteCRM 8 is shipped as a Composer project, and its Angular frontend requires Node.js 18+ to rebuild assets when you customise modules.
Install Composer 2
cd /tmp
curl -sS https://getcomposer.org/installer -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
composer --versionExpected output:
Composer version 2.7.7 2024-06-10 22:11:12Install Node.js 18 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --versionExpected output:
v18.20.4
10.7.0Node 18 is the minimum supported version for the SuiteCRM 8 frontend build pipeline. Node 20 also works but pin to 18 if you plan to follow the official docs exactly.
Step 5: Download SuiteCRM 8
You have two options: download the pre-built zip release (fastest, recommended for most deployments) or clone the Composer project (best for teams who want Git-tracked customisations).
Option A: Pre-Built Release Zip (Recommended)
Download the latest SuiteCRM 8 release from suitecrm.com/download:
cd /tmp
wget https://suitecrm.com/files/162/SuiteCRM-8.6/665/SuiteCRM-8.6.2.zipCreate the webroot and extract:
sudo mkdir -p /var/www/suitecrm
sudo unzip -q /tmp/SuiteCRM-8.6.2.zip -d /var/www/suitecrm
sudo chown -R suitecrm:www-data /var/www/suitecrmOption B: Composer Install (Git-Tracked Customisations)
sudo -u suitecrm composer create-project salesagility/suitecrm-src /var/www/suitecrm "^8.6"
cd /var/www/suitecrm
sudo -u suitecrm composer install --no-dev --optimize-autoloaderSet Correct Permissions
Whichever option you used, apply the permission model SuiteCRM requires:
cd /var/www/suitecrm
sudo find . -type d -exec chmod 2755 {} \;
sudo find . -type f -exec chmod 0644 {} \;
sudo chmod -R g+w cache custom modules themes data upload public/legacy/cache public/legacy/custom public/legacy/modules public/legacy/themes public/legacy/data public/legacy/upload 2>/dev/null || true
sudo chown -R suitecrm:www-data /var/www/suitecrmwww-data must be able to write to the listed directories; the g+w flag combined with the 2755 setgid bit ensures new files inherit group ownership.
Step 6: Run the SuiteCRM Installer
SuiteCRM 8 ships with a command-line installer that is faster and more reliable than the legacy web installer. Run it as the suitecrm user:
cd /var/www/suitecrm
sudo -u suitecrm php bin/console suitecrm:app:install \
-u "admin" \
-p "ChangeThisAdminPassword!" \
-U "suitecrm" \
-P "ChangeThisStrongPassword!" \
-H "localhost" \
-N "suitecrm" \
-S "https://crm.yourcompany.com" \
-d "no" \
-i "yes"Flag explanation:
-u/-p-- SuiteCRM admin username and password (stored in theuserstable)-U/-P-- MariaDB username and password from Step 3-H-- database host (localhostfor a local MariaDB)-N-- database name-S-- Site URL -- this is critical, must match the URL users will use (we will issue a cert for it in Step 8)-d-- demo data (nofor production,yesfor a test sandbox)-i-- interactive confirmations (yesprompts,noassumes defaults)
.env.local with your database credentials and APP_SECRETvar/cache/prod)Expected output (abbreviated):
// Running SuiteCRM Installer[OK] System checks passed [OK] Database connection established [OK] Legacy installation complete [OK] Symfony cache warmed [OK] Admin user created
SuiteCRM installed successfully. URL: https://crm.yourcompany.com Admin: admin
If the installer fails, it is almost always a permissions issue or a missing PHP extension -- scroll back through the output to find the first [ERR] line.
Post-Install Configuration
Open .env.local in the project root and verify these values:
sudo -u suitecrm nano /var/www/suitecrm/.env.localAPP_ENV=prod
APP_DEBUG=0
APP_SECRET=<generated>
DATABASE_URL="mysql://suitecrm:[email protected]:3306/suitecrm?charset=utf8mb4"
SUITE_INSTALLED=trueIn prod mode, SuiteCRM hides detailed error traces from end users. Never set APP_ENV=dev on a public server.
Step 7: Configure the Web Server (Nginx or Apache)
SuiteCRM 8 has a front controller pattern: all requests go through public/index.php, which then delegates to either the new Symfony/Angular app or the legacy v7 code at public/legacy/. Your web server configuration must rewrite URLs to this single entry point.
Pick one of the two web servers below.
Option A: Nginx (Recommended)
Install Nginx if you have not already -- see How to Install and Configure Nginx on Ubuntu 24.04 for the full walkthrough:
sudo apt install -y nginxCreate the SuiteCRM server block:
sudo nano /etc/nginx/sites-available/suitecrmPaste:
server { listen 80; server_name crm.yourcompany.com; root /var/www/suitecrm/public; index index.php;client_max_body_size 50m;
# Block sensitive files location ~* /(\.env|\.git|composer\.(json|lock)|package(-lock)?\.json) { deny all; return 404; }
# Legacy v7 code lives under /legacy location /legacy { try_files $uri $uri/ /legacy/index.php?$query_string; }
# Main SuiteCRM 8 front controller location / { try_files $uri $uri/ /index.php?$query_string; }
location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_read_timeout 300; }
# Deny PHP execution in upload / cache dirs location ~ /(cache|upload|custom/history)/.\.php$ { deny all; }
access_log /var/log/nginx/suitecrm_access.log; error_log /var/log/nginx/suitecrm_error.log; }
Enable the site:
sudo ln -s /etc/nginx/sites-available/suitecrm /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginxOption B: Apache
If you prefer Apache, install it with PHP-FPM integration:
sudo apt install -y apache2 libapache2-mod-fcgid
sudo a2enmod rewrite proxy_fcgi setenvif headers
sudo a2enconf php8.2-fpmCreate a virtual host:
sudo nano /etc/apache2/sites-available/suitecrm.conf<VirtualHost *:80> ServerName crm.yourcompany.com DocumentRoot /var/www/suitecrm/public<Directory /var/www/suitecrm/public> Options -Indexes +FollowSymLinks AllowOverride All Require all granted </Directory>
<FilesMatch \.php$> SetHandler "proxy:unix:/var/run/php/php8.2-fpm.sock|fcgi://localhost/" </FilesMatch>
ErrorLog ${APACHE_LOG_DIR}/suitecrm_error.log CustomLog ${APACHE_LOG_DIR}/suitecrm_access.log combined </VirtualHost>
Enable the site:
sudo a2ensite suitecrm
sudo a2dissite 000-default
sudo apachectl configtest
sudo systemctl reload apache2SuiteCRM ships .htaccess files for Apache, so the rewrite rules work automatically with AllowOverride All.
Step 8: Issue a Let's Encrypt TLS Certificate
A CRM contains some of the most sensitive data your business owns -- never run it over plain HTTP. Use Certbot to issue a free TLS certificate from Let's Encrypt.
For Nginx
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d crm.yourcompany.com --redirect --agree-tos -m [email protected] -nFor Apache
sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d crm.yourcompany.com --redirect --agree-tos -m [email protected] -nExpected output:
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/crm.yourcompany.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/crm.yourcompany.com/privkey.pem
Deploying certificate
Successfully deployed certificate for crm.yourcompany.comCertbot installs a systemd timer that auto-renews the certificate every 60 days. Verify it:
sudo systemctl status certbot.timer
sudo certbot renew --dry-runVisit https://crm.yourcompany.com in your browser -- you should see the SuiteCRM 8 login screen served over TLS.
Step 9: Schedule the SuiteCRM Cron Job
SuiteCRM relies on a scheduler to send campaign emails, poll inbound email accounts, check for workflow triggers, run reports, and clean stale sessions. Without cron, none of these work.
Open the suitecrm user's crontab:
sudo crontab -e -u suitecrmAdd this single line:
* cd /var/www/suitecrm && /usr/bin/php -f bin/console cron:run > /dev/null 2>&1The cron:run console command replaces the legacy cron.php entry point. It dispatches both Symfony/Messenger jobs and legacy v7 scheduled tasks (campaigns, inbound email, reports) in a single invocation, and it short-circuits quickly if nothing is due -- safe to run every minute.
Verify cron is firing after a minute or two:
sudo tail -f /var/log/syslog | grep CRONInside SuiteCRM, navigate to Admin -> Scheduler and confirm the built-in jobs (Prune Tracker Tables, Check Inbound Mailboxes, Run Report Generation Scheduled Tasks, etc.) show a recent "Last Run" timestamp.
Step 10: First Login and Admin Panel Tour
Browse to https://crm.yourcompany.com and log in with the admin credentials from Step 6.
On first login, SuiteCRM 8 drops you on the home dashboard with the Symfony/Angular UI. Click the avatar in the top-right and choose Admin Panel (the URL is /legacy/index.php?module=Administration&action=index -- most admin screens still live in the v7 legacy UI during the 8.x transition).
Immediate configuration tasks:
System Settings
Admin -> System Settings
- Site URL -- confirm it matches your HTTPS domain; mismatches break the Angular routing
- Default currency -- set your primary currency
- Logs -- set log level to
fatalfor production (infoordebugfor troubleshooting) - Display stack trace -- unchecked in production
Locale
Admin -> Locale
- Default timezone (UTC is safest for a multi-region team)
- Default date/time format
- Name display format
- Currency format (thousands/decimal separators)
Email Settings
Admin -> Email Settings
Configure the outbound SMTP relay SuiteCRM uses for campaigns, password resets, and workflow notifications. Typical SendGrid config:
- SMTP Server:
smtp.sendgrid.net - Port:
587 - Use TLS/SSL:
TLS - Username:
apikey - Password:
<your SendGrid API key> - From Name / From Address: a verified sender on your domain
Password Management
Admin -> Password Management
- Minimum length (12+ recommended)
- Lockout policy (e.g. 5 failed attempts = 30-minute lockout)
- Expiration interval (90 days for most compliance regimes)
Role Management
Admin -> Role Management
Create roles for Sales Reps, Sales Managers, Marketing, Support, and Read-Only users. Assign users to roles via User Management. Roles control both module-level access (can user see Quotes?) and field-level access (can user see the amount field on Opportunities?).
Post-Install: Campaigns, Workflows, and Studio
Three areas of SuiteCRM are worth learning well -- they are the day-one differentiators from lightweight CRMs.
Campaigns -- Your First Email Blast
SuiteCRM's Campaigns module runs full email marketing directly from your CRM, using the SMTP relay you configured above.
Campaigns runs by the scheduler and set the from-address$contact_first_name)Track opens, clicks, bounces, and unsubscribes on the campaign ROI dashboard.
Workflows -- Automate Record Actions
The Process Definitions module (BPMN-inspired) and the simpler legacy Workflow module together automate repetitive actions.
Example workflow: When Opportunity stage changes to "Closed Won", create a task for the Account Manager to schedule onboarding, email the customer a welcome message, and notify #sales on Slack via a webhook.
Build it in Workflow Management -> Create Workflow:
- Target module: Opportunities
- Condition:
sales_stageequalsClosed Won - Actions: Create Task, Send Email, Call URL
Studio -- Customise Without Code
Admin -> Studio is the drag-and-drop module editor. You can:
- Add custom fields to any module (text, dropdown, currency, date, relate)
- Edit the layout of Detail View, Edit View, List View, and Search
- Add custom relationships (one-to-many, many-to-many)
- Create completely new custom modules via Module Builder
custom/ (and public/legacy/custom/) -- upgrades preserve your customisations automatically.Authentication: LDAP and SAML
Most organisations want CRM logins to flow from Active Directory, Okta, Google Workspace, or Microsoft Entra ID.
LDAP / Active Directory
Admin -> Password Management -> Enable LDAP Authentication
- Server:
ldaps://dc01.yourcompany.local - Port:
636 - Bind Attribute:
sAMAccountName(AD) oruid(OpenLDAP) - User DN / Password: service account for binding
- Base DN:
OU=Users,DC=yourcompany,DC=local
SAML 2.0 SSO
SuiteCRM 8 supports SAML through the bundled SimpleSAMLphp integration:
Admin -> Password Management -> Enable SAML Authentication
- Identity Provider Login URL: your IdP's SSO endpoint
- Identity Provider SLO URL: single-logout endpoint
- X.509 Certificate: paste IdP public cert
- Field Mappings: map SAML attributes (
emailaddress,givenname,surname) to SuiteCRM user fields
Backups and Upgrades
Nightly Backup Script
Create /usr/local/bin/suitecrm-backup.sh:
#!/bin/bash
set -euo pipefail
STAMP=$(date +%F_%H%M)
BACKUP_DIR=/var/backups/suitecrm
mkdir -p "$BACKUP_DIR"Database dump
mysqldump --single-transaction --routines --triggers \
-u suitecrm -p'ChangeThisStrongPassword!' suitecrm \
| gzip > "$BACKUP_DIR/db-$STAMP.sql.gz"Files (uploads, custom, config)
tar -czf "$BACKUP_DIR/files-$STAMP.tgz" \
-C /var/www/suitecrm \
upload custom public/legacy/upload public/legacy/custom .env.localRetain 14 days
find "$BACKUP_DIR" -type f -mtime +14 -deletesudo chmod 700 /usr/local/bin/suitecrm-backup.sh
sudo crontab -eAdd:
30 2 * /usr/local/bin/suitecrm-backup.shFor production, push the /var/backups/suitecrm directory to off-site storage (S3, Backblaze B2, Hetzner Storage Box) via rclone or restic.
Upgrading SuiteCRM
SuiteCRM 8 ships an in-place upgrade console command:
cd /var/www/suitecrm
sudo -u suitecrm php bin/console suitecrm:app:upgrade \
--package=/tmp/SuiteCRM-Upgrade-8.6.2-to-8.7.0.zip \
--target-version=8.7.0Always:
suitecrm-backup.sh)php bin/console suitecrm:app:maintenance-mode --enablephp bin/console cache:clear --env=prod && php bin/console cache:warmup --env=prodBetween minor versions (8.x -> 8.y), the upgrader is well-tested. Between major versions (7.x -> 8.x) there is a one-time migration utility -- read the official upgrade docs before running it.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
Fatal error: Allowed memory size exhausted during install | PHP memory_limit too low | Raise to 512M in /etc/php/8.2/fpm/php.ini and /etc/php/8.2/cli/php.ini, then sudo systemctl restart php8.2-fpm |
| White page after login, 500 in browser console | Front controller not rewriting; legacy paths missing | Confirm Nginx try_files ... /index.php?$query_string and the /legacy location block; for Apache ensure AllowOverride All and that .htaccess is present in /var/www/suitecrm/public |
Could not open input file: bin/console | Ran the command from the wrong directory | Always cd /var/www/suitecrm before running bin/console |
| Campaign emails never send | Cron not configured or wrong user | Verify sudo crontab -l -u suitecrm and check Admin -> Scheduler for a recent Last Run; tail /var/log/syslog for CRON lines |
| "You do not have access" on modules you should see | Role Management denies access, or ACL cache stale | Check Admin -> Role Management for the user's role; then Admin -> Repair -> Quick Repair and Rebuild |
| Studio changes not visible | Legacy cache holds the old metadata | Admin -> Repair -> Quick Repair and Rebuild, then php bin/console cache:clear --env=prod |
Error 1366: Incorrect string value on insert | Database not using utf8mb4 | Recreate DB with CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci and re-run installer |
| Inbound mailbox not pulling email | php8.2-imap missing, or IMAP credentials wrong | sudo apt install -y php8.2-imap && sudo systemctl restart php8.2-fpm, then test in Admin -> Inbound Email |
| File upload fails silently at ~2MB | upload_max_filesize / post_max_size default is 2M | Set both to 50M in php.ini, restart PHP-FPM, and set client_max_body_size 50m; in Nginx |
| HTTPS works but Angular app shows "Site URL mismatch" | SITE_URL in config doesn't match browser URL | Admin -> System Settings -> Site URL -- update to full https:// URL, save, clear cache |
| Slow page loads after a few weeks | Bloated tracker and job_queue tables | Scheduler runs "Prune Database on the 1st of the Month" by default -- confirm it is active, or truncate tracker manually |
Viewing Logs
# SuiteCRM legacy log
sudo tail -f /var/www/suitecrm/public/legacy/suitecrm.logSymfony log
sudo tail -f /var/www/suitecrm/var/log/prod.logPHP-FPM errors
sudo tail -f /var/log/php8.2-fpm.logNginx errors
sudo tail -f /var/log/nginx/suitecrm_error.logFAQ
What is the difference between SuiteCRM 7 and SuiteCRM 8?
SuiteCRM 7 is the continuation of the SugarCRM Community Edition codebase -- a mature, Smarty-template-based PHP application with proven business logic and a very large module ecosystem. SuiteCRM 8 is a re-architecture that keeps all of that business logic and data model but wraps it in a modern Symfony 6 backend with an Angular frontend. Visually, v8 is faster, responsive, and mobile-friendly. Under the hood, the legacy v7 code still runs at /legacy/ and handles admin screens that have not yet been ported. SuiteCRM 7 is still supported for security fixes, but all new development targets v8. New deployments should install v8.
Is SuiteCRM really free?
Yes -- SuiteCRM is released under AGPL v3 with no paid tier, no "community edition" vs "enterprise edition" split, and no per-user fees. You can download it, install it, run it commercially, and modify it at no charge. SalesAgility (the company behind it) earns revenue by selling support contracts, hosting, and custom development services, but nothing in the software itself is paywalled. The AGPL license does mean that if you offer SuiteCRM as a hosted service to third parties, you must make your modifications available to your users -- but running it for your own company imposes no such obligation.
Can SuiteCRM handle a 100-user team?
Absolutely. SuiteCRM is deployed at organisations with thousands of users and tens of millions of records. The bottleneck is almost always the database -- on MariaDB 10.11 with the InnoDB buffer pool sized to half your RAM, a single VPS can comfortably support 50-100 concurrent active users. Above that, scale horizontally with a dedicated database server and a load-balanced pair of web servers sharing /upload over NFS or object storage. For 500+ users, tune opcache, enable Redis for sessions, and shard the tracker table.
How do I migrate from Salesforce / HubSpot / Zoho to SuiteCRM?
SuiteCRM has a built-in Import Wizard under every module (Contacts -> Import, Accounts -> Import, etc.) that accepts CSV files with field mapping. The standard migration flow is: export from your source CRM as CSV, map the fields in SuiteCRM's wizard, import Accounts first, then Contacts (linked by Account name), then Opportunities, then historical Activities. For large or complex migrations, SuiteCRM's REST v8 API supports bulk record creation with full relationship linking. Commercial migration connectors from SalesAgility and third-party vendors handle the tricky bits like attaching historical emails and call recordings.
Does SuiteCRM integrate with Mautic, Outlook, or VoIP systems?
Yes to all three. Mautic has an official SuiteCRM plugin for bidirectional lead sync -- see our Mautic install guide for the server side. Outlook integration is available through the official SuiteCRM Outlook Plugin (track emails, sync calendar/contacts) and the community CRMOutlookSync project. For VoIP, Asterisk and 3CX integrations exist as community modules, and any SIP-compliant PBX can be wired in via click-to-call URLs and inbound webhook lead creation. For modern CPaaS, Twilio's API is a few lines of custom logic-hook code.
Can I run SuiteCRM in Docker instead?
Yes. SuiteCRM publishes an official bitnami/suitecrm image, and the community maintains Docker Compose stacks that bundle SuiteCRM + MariaDB + Nginx. Docker is a great fit for development and for teams already running a container orchestrator. For a single-tenant production deployment on a VPS, the bare-metal install in this guide is simpler to secure, back up, and upgrade -- fewer moving parts and no container-layer filesystem overhead. If you want a Docker path, start from the official Docker guide and pair it with our LEMP stack tutorial for the host-side reverse proxy.
Next Steps
Now that SuiteCRM 8 is running on your VPS, build on the foundation:
- Pair SuiteCRM with Mautic for marketing automation -- Install Mautic on a separate subdomain, enable the official SuiteCRM plugin, and sync leads and segments bidirectionally. Mautic handles email nurture drips and lead scoring; SuiteCRM handles pipeline and deals.
- Expose the REST v8 API -- SuiteCRM ships a full OAuth2-protected REST API. Create a client credential in Admin -> OAuth2 Clients and Tokens and integrate with your website forms, billing system, or custom mobile app. Docs at docs.suitecrm.com/developer/api.
- Build a customer portal -- Install the official SuiteCRM Portal Module to give customers self-service access to their cases, knowledge base articles, and invoices -- dramatically reducing support ticket volume.
- Monitor with Uptime Kuma and Prometheus -- Deploy Uptime Kuma to alert on login-page downtime; export MariaDB and PHP-FPM metrics to Prometheus for long-term performance tracking.
- Harden further -- Add fail2ban rules for the SuiteCRM login endpoint, enable HTTP/2 in Nginx, and set strict Content-Security-Policy headers. For a walkthrough, see our Nginx hardening guide.
- Explore the module library -- Browse store.suitecrm.com for commercial modules (advanced reporting, DocuSign, Stripe billing, telephony) and the community GitHub organisation for free extensions.
Run SuiteCRM on Infrastructure That Scales With You>
SuiteCRM rewards fast disks, plenty of RAM, and low-latency networking. Our CloudCore Professional plan is purpose-built for self-hosted business applications:>
- 6 vCPU cores, 12 GB RAM, 100 GB NVMe SSD
- Unmetered bandwidth on a 1 Gbps port
- Snapshots and nightly backups included
- 24/7 support from engineers who run SuiteCRM in production
- Free migration assistance from Salesforce, HubSpot, or existing SuiteCRM hosts>
Launch Your CloudCore Professional VPS -- EUR 19.99/month, deploy in under 60 seconds.