Free tools Windows power users keep installed
One-click scans. No signup required.
To move Moodle to a new domain, migrate the database, Moodle code, and moodledata, set the new fixed URL in config.php, replace old absolute URLs in the database, and test the complete site before changing DNS. Changing only $CFG->wwwroot does not repair links to images, files, plugins, or course content that were saved with the old hostname.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What changes when Moodle gets a new domain?
A Moodle domain change is both a server move and a URL-data migration. The public address is controlled by the $CFG->wwwroot value in the Moodle root config.php. The database, however, can contain absolute links in course text, labels, pages, plugin settings, file references, webhooks, and identity-provider configuration. Those links remain unchanged until you run Moodle’s replacement tool.
As an Amazon Associate I earn from qualifying purchases.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsMoodle’s configuration documentation describes wwwroot this way: “This setting must be a fixed URL (a string constant) that points to your site.” A dynamic value based on the current request host is unsupported and can prevent command-line maintenance scripts from working. The same setting must use the HTTPS address when you move from HTTP to HTTPS; Moodle states, “If you change your site from http to https, you MUST update this setting.” See the Moodle configuration-file documentation.
Plan the cutover before touching DNS
Do the work on a destination server or temporary hostname first. DNS should be the final traffic switch, not the first configuration change. Keep the old site available until users can log in, courses render correctly, scheduled tasks run, and integrations have been verified.
- Record the current Moodle version, PHP version, database engine and version, web server, enabled plugins, cron command, mail settings, and external integrations.
- Choose the final canonical URL, including scheme and any path. For example, decide whether the site will be
https://new.example.eduorhttps://new.example.edu/moodle. The value must match the URL users actually enter. - Lower the DNS record’s TTL in advance if you need a faster cutover. This affects resolver caching but does not migrate Moodle data.
- Prepare a TLS certificate covering the new hostname if HTTPS will be used.
- Plan a maintenance window. Moodle’s migration documentation gives an illustrative estimate of about 15 minutes for a small site, but that is not a universal duration; large databases, file stores, slow backups, and plugin checks can make the window much longer.
Complete migration procedure
1. Enable maintenance mode and stop changes
Sign in as a site administrator and enable maintenance mode before taking the backup. Maintenance mode prevents students and teachers from editing content while files and database records are being copied. Also pause automated imports, enrolment synchronisation, grading integrations, and other jobs that could write data during the move. If cron runs from a system scheduler, stop or temporarily disable it for the migration window.
Keep a record of the exact time maintenance mode was enabled. Any changes made after the database backup but before the cutover will not be present on the destination.
Recommended Free Tools
2. Back up the database and files
Create a restorable database backup using the database engine’s native tooling or your established backup system. Verify that the backup can be read and record where it is stored. A screenshot that a backup job completed is not a substitute for a usable dump.
Copy the Moodle application directory and the complete moodledata directory to the destination. Moodle’s current migration guidance notes that the cache, localcache, sessions, temp, and trashdir subdirectories do not need to be copied; Moodle can recreate them. Preserve the rest of moodledata, especially uploaded files, courses, assignments, backups, and generated content.
Do not expose moodledata through the web server. It should be outside the document root or otherwise blocked from direct HTTP access. Preserve ownership and permissions when copying, then set them explicitly on the destination rather than assuming the source server’s numeric user and group IDs are identical.
3. Build the destination web and database environment
Install a Moodle-compatible PHP runtime, required PHP extensions, the supported database server, and a web server configuration appropriate for the Moodle version you are running. Copy the code to the destination and restore the database into a new database or an intentionally selected existing one. Set the database name, username, password, host, and port in config.php for the destination environment.
Set the dataroot path to the destination’s absolute moodledata location. The web-server account must be able to read Moodle code and read/write the directories Moodle requires, while the database credentials should have only the privileges needed by that Moodle database. Incorrect permissions commonly appear as missing files, failed plugin operations, or errors when Moodle tries to create cache directories.
Before opening the site publicly, configure a temporary host entry, staging hostname, or load-balancer route that reaches the destination. This lets you test the new installation without sending ordinary users to it.
4. Set the authoritative URL in config.php
Edit the config.php in the Moodle root on the destination. Set $CFG->wwwroot to one fixed string containing the final scheme, hostname, and optional path:
<?php
$CFG->wwwroot = 'https://new.example.edu/moodle';Use the exact public URL, without a trailing slash unless your existing configuration and deployment specifically require one. Do not calculate it from $_SERVER, request headers, or the current browser host. Moodle’s documentation warns that a dynamic URL is unsupported and can stop command-line scripts from operating reliably.
Check the other environment-specific values in the same file, particularly $CFG->dataroot, database settings, directory paths, and any custom reverse-proxy or cookie settings. Keep the old wwwroot out of the destination configuration.
5. Configure HTTPS consistently
If the new address is HTTPS, the certificate, web server or proxy, and Moodle must agree on that public URL. Install a certificate for the new hostname, configure the TLS listener, and ensure HTTP requests are redirected to HTTPS only once. Then use the HTTPS URL in $CFG->wwwroot.
There are two common TLS layouts:
| Layout | Where TLS ends | Moodle setting and operational concern |
|---|---|---|
| Direct web-server TLS | The same web server that serves Moodle | Usually no proxy-specific flags are needed. Configure the certificate, HTTPS virtual host, and HTTP-to-HTTPS redirect on that server. |
| Reverse-proxy or external SSL appliance | A load balancer, proxy, or SSL appliance in front of the Moodle web server | Set $CFG->reverseproxy = true only when Moodle is actually behind a reverse proxy. Set $CFG->sslproxy = true when an external device terminates HTTPS and forwards the request internally over HTTP. Configure these according to the maintained Moodle config-dist.php template; enabling them on a direct deployment can create incorrect scheme detection or redirect loops. |
The proxy must pass the original host and scheme in the headers expected by your web-server configuration, and it must trust those headers only from the proxy network. A certificate that covers the old hostname, an incorrect forwarded scheme, or a mismatch between proxy routing and wwwroot can produce browser certificate errors, endless redirects, or mixed-content warnings.
6. Replace old absolute URLs in Moodle’s database
Changing wwwroot controls newly generated links; it does not rewrite absolute URLs already stored in content. After the destination can connect to the restored database, sign in as an administrator and open:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
{wwwroot}/admin/tool/replace/index.php
With the new wwwroot in the address bar, this might be https://new.example.edu/moodle/admin/tool/replace/index.php. Enter the complete old base URL as the search value and the complete new base URL as the replacement value. Include the scheme and any path, for example:
Old: http://old.example.edu/moodle
New: https://new.example.edu/moodleTake a fresh database backup immediately before running the replacement. Review the values carefully: replacing a short hostname fragment instead of the complete base URL can alter unrelated text. The tool repairs absolute links embedded in database content, including links to files and images. It does not replace values in external systems that are not stored in Moodle’s database, so review identity-provider callbacks, webhooks, mail templates, reverse-proxy rules, and third-party integrations separately.
7. Test the destination before cutover
Use a test account as well as an administrator account. Check each item below from the destination hostname:
- Login, logout, password reset, session persistence, and multi-factor or single-sign-on flows.
- Home page, dashboard, course navigation, search, enrolment, gradebook, assignment submission, and quiz attempts.
- CSS, JavaScript, themes, language packs, and browser developer-console errors.
- Embedded images, audio, video, downloadable files, SCORM packages, and links inside course content.
- File upload and deletion, backup and restore, repository connections, and plugin pages.
- Cron execution, task queues, scheduled backups, outgoing mail, incoming mail if enabled, and any webhooks.
- Identity-provider return URLs, OAuth or API callbacks, mobile-app endpoints, and integrations that whitelist the old hostname.
- HTTP requests to the old hostname, including whether a deliberate redirect is safe and whether sensitive POST requests need special handling.
Inspect generated page source and network requests for the old hostname. Also search configuration files and integration dashboards, because a successful page load does not prove that every callback has been updated.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Rank #4
8. Change DNS and complete the cutover
After testing, point the new DNS record to the validated destination and update firewall, load-balancer, WAF, and monitoring rules. If the old hostname should remain usable, configure a permanent redirect at the old web server after confirming that it will not interfere with login or non-idempotent requests.
Keep the old installation in a read-only or maintenance state during propagation so users cannot create divergent data sets. Monitor logs, login success, cron output, mail delivery, storage growth, and error rates. Once the new hostname is confirmed from multiple networks, disable maintenance mode on the new site. Do not delete the old copy until your backup and rollback plan has survived the agreed observation period.
Why images and files still show the old domain
This symptom almost always means that absolute links were stored in database content before the move. A new wwwroot changes links Moodle generates dynamically, but it cannot infer and rewrite every URL inside a course page, label, question, plugin setting, or HTML block. Run the replacement tool after restoring the final database and use the exact old and new base URLs.
If old links remain after replacement, check the following branches:
- Only a few course pages are affected: inspect the HTML in those activities for a different old path, port, or hostname alias and correct the content.
- All files fail: verify
$CFG->dataroot, filesystem ownership, and web-server access rules. A URL replacement cannot fix a missing or unreadable dataroot. - The browser reports mixed content: search for
http://references that were not covered by the replacement value, then update them to the HTTPS base URL. - Images redirect to the old host: check plugin settings, reverse-proxy rules, CDN configuration, and cached HTML outside Moodle’s database.
- New pages work but command-line tasks fail: confirm that
wwwrootis a literal fixed string and that the CLI process reads the sameconfig.phpas the web process.
Common failure modes and recovery
Redirect loop after enabling HTTPS
Confirm where TLS terminates. If a proxy handles HTTPS and forwards HTTP internally, Moodle needs the proxy settings appropriate to that architecture and the proxy must send a trustworthy forwarded scheme. If TLS terminates directly on the Moodle web server, remove proxy-only flags and check that the HTTP-to-HTTPS redirect is defined in one place rather than duplicated by the proxy and origin.
Users are logged out repeatedly
Verify that every request reaches the same canonical hostname, that the site is not alternating between HTTP and HTTPS, and that proxy host and scheme headers are consistent. Clear browser cookies after a domain change and inspect cookie-domain or secure-cookie settings if the problem affects all accounts.
Best Value
CSS or JavaScript returns 404 or an old URL
Inspect the browser network panel for the requested host and path. Confirm the fixed wwwroot, run the database replacement for stored references, purge Moodle caches from the administrator interface or the normal CLI maintenance process, and check that the web server points to the correct Moodle code directory.
Cron, CLI upgrade, or scheduled tasks fail
Run the command with the destination installation’s PHP binary and verify that it loads the destination config.php. A computed wwwroot, wrong dataroot permissions, unavailable database credentials, or a path copied from the old server can break CLI execution even when browser pages appear normal.
Some plugins or single-sign-on callbacks stop working
Update the callback and redirect URLs in each external provider, API client, webhook sender, mail gateway, and plugin configuration. These systems may validate an exact hostname and will not be changed by Moodle’s database replacement tool.
The migration must be rolled back
Put the new site into maintenance mode, stop writes, restore DNS to the old validated host, and keep the destination database backup and logs. If users wrote data to the destination after cutover, do not silently discard it; determine whether a controlled data export or a second migration is required. Rollback is safest when the old site remained untouched and available throughout the observation period.
Choosing an implementation approach
The right method depends on who operates the infrastructure and how much control is required. These choices affect the work around Moodle; they do not remove the need to set wwwroot, migrate the database and dataroot, replace stored URLs, and test.
| Decision | Option | Advantages | Trade-offs |
|---|---|---|---|
| TLS placement | Direct web-server TLS | Fewer moving parts and straightforward scheme detection. | You manage certificates, HTTPS virtual hosts, renewal, and any load balancing on the Moodle server. |
| TLS placement | Reverse-proxy termination | Central certificate management, shared edge security controls, and flexible routing across application servers. | Requires correct forwarded-host and forwarded-scheme handling and the appropriate Moodle proxy settings; troubleshooting is split between proxy and origin. |
| Infrastructure | Self-managed VPS | Full control over operating system, PHP/database versions, filesystem, cron, firewall, and maintenance timing. | You are responsible for patching, backups, permissions, monitoring, TLS, and recovery testing. |
| Infrastructure | Managed Moodle hosting | The provider may handle the operating system, backups, updates, monitoring, and migration assistance. | Maintenance access, supported Moodle versions, proxy design, backup retention, and cutover controls depend on the provider’s service terms. Confirm these before scheduling a move. |
| Database URL changes | Manual replacement | Useful for a small, well-understood migration where an administrator can review the old and new base URLs directly in the replacement interface. | It is easy to mistype a scheme, path, or hostname and it depends on a verified backup and careful review. |
| Database URL changes | Scripted, backed-up process | Repeatable for staging and production, easier to log, and suitable for infrastructure-as-code workflows. | Scripts must be written for the specific Moodle version and database, tested against a copy, and protected against an over-broad search-and-replace. |
Final verification checklist
$CFG->wwwrootis a fixed final URL, including the correct HTTPS scheme and path.- The destination database, Moodle code, and
moodledataare complete, readable, writable where required, and protected from direct web access. - The old base URL was replaced in Moodle’s database from a fresh backup.
- Proxy flags are enabled only when the deployment actually uses a reverse proxy or external SSL terminator.
- Certificate, web-server routing, DNS, firewall, load balancer, and redirects all use the same canonical hostname.
- Login, course content, files, plugins, cron, mail, webhooks, and identity-provider callbacks have been tested.
- The old installation remains available for rollback until the new site has been observed successfully.
Once these checks pass, a Moodle domain change is complete: configuration points to the new public address, stored content points there as well, and the surrounding infrastructure agrees on the same host and HTTPS scheme.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
