SuiteCRM v8+ Migration Guide (Server to Server)

📦 Prerequisites

Before you begin:

• You have a full backup of:
  • SuiteCRM project files (e.g., zipped copy of /crm)
  • MySQL database (.sql or .gz)
• SSH or FTP access to both old and new servers
• PHP 7.4+ or 8.x with required extensions (esp. pdo_mysql, openssl)
• Apache/Nginx with proper vhost config

🔁 Step-by-Step Migration Process

🧳 Step 1: Transfer Project Files

Copy files from old server to new server using SCP, FTP, or rsync:

scp -r /path/to/suitecrm user@new-server:/path/to/new-directory

Or unzip your archive on the new server:

unzip suitecrm_backup.zip -d /var/www/html/crm

💾 Step 2: Import the Database

Upload and import your .sql file:

mysql -u root -p
CREATE DATABASE Suitecrm_crm;
exit

mysql -u root -p Suitecrm_crm < /path/to/your_backup.sql

🔐 Step 3: Create MySQL User & Grant Permissions

CREATE USER 'Database_user'@'localhost' IDENTIFIED BY 'Sdf%3kjas72dsHG';
GRANT ALL PRIVILEGES ON Suitecrm_crm.* TO 'Database_user'@'localhost';
FLUSH PRIVILEGES;

👉 If using MySQL 8+, enforce compatibility:

ALTER USER 'Database_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'Sdf%3kjas72dsHG';

⚙️ Step 4: Update config.php

Edit /path/to/crm/config.php:

'dbconfig' => array(
  'db_host_name' => 'localhost',
  'db_user_name' => 'Database_user',
  'db_password' => 'Sdf%3kjas72dsHG',
  'db_name' => 'Suitecrm_crm',
  'db_type' => 'mysql',
  'db_port' => '3306',
  'db_manager' => 'MysqliManager',
),

🌐 Step 5: Set DATABASE_URL in .env.local

SuiteCRM v8+ uses Symfony, so update .env.local:

URL-Encode the password:

• *gBsRUe#.8;$ becomes: %2AgBsRUe%23.8%3B%24

Final entry:

DATABASE_URL="mysqli://Database_user:Sdf%3kjas72dsHG@127.0.0.1:3306/Suitecrm_crm"

Save and exit:

nano .env.local

🧹 Step 6: Clear All Caches

# Symfony cache
php bin/console cache:clear --env=prod

# SuiteCRM cache
rm -rf cache/*
rm -rf upload/cache/*
rm -rf var/cache/*

🔐 Step 7: Fix File Permissions

cd /path/to/crm
chown -R apache:apache .     # or www-data for Ubuntu
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 775 cache custom modules upload

🌍 Step 8: Update site_url in config.php

'site_url' => 'https://yourdomain.com/crm',

🧪 Step 9: Test the Login

Visit:

https://yourdomain.com/crm/

Try logging in as admin. If it fails:

Reset Password from MySQL:

UPDATE users SET user_hash = MD5('newpassword') WHERE user_name = 'admin';

🔄 Step 10: Run Quick Repair & Rebuild

After logging in:

Admin → Repair → Quick Repair and Rebuild

This is crucial to sync DB and metadata.