What Actually Breaks When Claroline Moves

Claroline Connect stores its identity in more places than a single database table, and that is the source of nearly every post-migration failure. When you copy an installation to a new domain, a new hosting account, or even a new document root under the same account, three independent things fall out of alignment at once: the PHP configuration file that holds database credentials and the absolute platform URL, the rows inside the database that cache absolute links, and the web server rewrite rules that assume a particular folder depth. A migration that touches only the files, or only the database, leaves the application in a half-broken state where the login page renders but every asset, course document, and AJAX call points at the old location.

The application is built on Symfony, so the authoritative configuration lives in app/config/parameters.yml (older 1.11 builds) within the Claroline web root. That file carries the database host, name, user, password, and the platform_url or domain_name entry used to build absolute URLs in emails and generated resource links. Symfony also writes a compiled container and cached routing to app/cache/prod/ (or var/cache/prod/ on newer trees). That cache bakes in the old paths and credentials, so even a perfect config edit appears to do nothing until the cache is cleared. On a shared account you cannot run console commands as a privileged user, but you can delete the cache directory contents through File Manager, which forces Symfony to rebuild on the next request using the corrected values.

The second trap is absolute data stored inside the database. Claroline writes full URLs into resource nodes, rich-text course content, announcement bodies, and the platform options table. If learners embedded images or links using the visual editor, those references hard-code https://old-domain.tld/.... A domain change that skips a controlled search-and-replace in phpMyAdmin leaves broken images scattered through courses even when the platform itself loads perfectly. Understanding these three layers before you touch anything keeps the migration predictable rather than a sequence of surprises.

Moving the Files and Database Without Root

Begin on the source account by producing a clean snapshot. In cPanel open File Manager, navigate to the Claroline web root (commonly /home/user/public_html or a subfolder like /home/user/public_html/lms), select every file and folder, and use Compress to build a single .zip or .tar.gz. Before compressing, empty the cache directory so you never carry stale compiled paths into the new home: delete the contents of app/cache/prod/ and app/logs/ (or var/cache/ and var/logs/). These rebuild automatically and only bloat the archive.

Export the database next. Open phpMyAdmin, select the Claroline schema, choose the Export tab, and use the Custom method so you can tick Add DROP TABLE and select SQL format. A Claroline course catalog with uploaded documents produces a large dump, so if the export times out in the browser, export table groups separately or use the phpMyAdmin export with gzip compression enabled to stay under the memory and execution ceilings on shared hosting.

On the destination account, create the landing database first. In cPanel use MySQL Databases to create a new database and a new user, then add that user to the database with All Privileges. DirectAdmin users do the same under Account Manager → MySQL Management. Record the exact database name, user, and password, because shared hosts prefix these with your account username (for example cpuser_claro), and the prefix almost never matches the source server. Import the dump through the new database's Import tab in phpMyAdmin. Then upload your archive to the new web root using File Manager and extract it in place.

Uploaded course files live under files/ (and data/ on some versions). These must retain their directory structure exactly, because resource nodes reference them by relative path. If the archive extracted cleanly, the tree is intact. Confirm that app/config/parameters.yml, the files/ directory, and the writable app/cache and app/logs folders all transferred. Set the writable directories back to 0755 via File Manager's Permissions dialog if extraction reset them.

Rewiring Configuration, Database URLs, and Rewrites

With files and schema in place, edit the configuration to match the new environment. In File Manager, right-click app/config/parameters.yml and choose Edit. Update the database block and the platform URL:

parameters:
    database_host: localhost
    database_port: null
    database_name: cpuser_claro
    database_user: cpuser_claro
    database_password: 'YourNewStrongPassword'
    platform_url: 'https://new-domain.tld'
    domain_name: 'new-domain.tld'
    secret: keep-the-existing-value

Leave the secret value unchanged; regenerating it invalidates existing sessions and encrypted tokens but is otherwise safe if you accept that every user must log in again. Keep database_host as localhost on shared hosting, since remote MySQL hostnames rarely apply within a single managed account.

Now purge the Symfony cache so the new values take effect. Delete everything inside app/cache/prod/ (keep the folder itself). On the next page load Claroline rebuilds the container against the corrected credentials and URL. If you see a blank white page or HTTP 500 at this point, the cache rebuild failed on permissions or a leftover compiled file; re-delete the cache contents and confirm the folder is writable, then check app/logs/prod.log through File Manager for the exact exception.

Fix the absolute links baked into content with a scoped phpMyAdmin query rather than a blind full-database replace. Target the options table and the rich-text columns that commonly hold full URLs:

UPDATE claro_platform_options
   SET value = REPLACE(value, 'old-domain.tld', 'new-domain.tld')
 WHERE value LIKE '%old-domain.tld%';

Repeat the pattern against text-bearing tables such as announcement and resource content columns, always keeping the WHERE ... LIKE filter so you only rewrite rows that actually contain the old host. Run a SELECT with the same condition first to preview how many rows will change.

Address rewrites last. Claroline serves through a front controller, and the .htaccess in the web root maps requests to it. When the document root changes to a subfolder, adjust RewriteBase to match:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /lms/
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ app.php [QSA,L]
</IfModule>

For a root-level install, use RewriteBase /. If you need to force HTTPS on the new domain, add a redirect above the front-controller rule so every learner and embedded asset uses the canonical scheme that matches platform_url:

RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://new-domain.tld/$1 [R=301,L]

Verifying the Migration and Avoiding Silent Failures

Confirm the PHP environment matches the source. Claroline is version-sensitive, so open cPanel MultiPHP Manager (or DirectAdmin's PHP version selector) and set the migrated domain to the same major PHP release the source ran, then use PHP Selector extensions to enable intl, gd, mbstring, zip, and pdo_mysql. A missing intl extension is a frequent cause of a working database connection paired with a 500 on the dashboard. Raise upload and memory ceilings for large course imports with a .user.ini in the web root:

memory_limit = 512M
upload_max_filesize = 128M
post_max_size = 128M
max_execution_time = 180

Log in as the platform administrator and walk through a single course that contains embedded images, a downloadable document, and an external link. Rendered images confirm the URL replacement worked; a successful file download confirms the files/ tree and its relative references survived the move. Send a password-reset email to yourself and confirm the link inside points at the new domain, which validates platform_url. If any asset still resolves to the old host, re-run the targeted phpMyAdmin replace against the specific table holding that content and clear the cache again.

When something stays broken, read the local log rather than guessing. app/logs/prod.log records database authentication failures, missing extensions, and permission errors with precise stack traces, and the LiteSpeed stderr.log in your account's logs surfaces front-controller crashes. Keep the source installation online and untouched until you have verified logins, course content, and email on the destination, so you always have a known-good fallback if the cutover needs a second pass.