Moving EspoCRM to a new server or database: what the work involves
Moving a self-hosted EspoCRM to new hardware, a new virtual machine or a different database engine is a planned transfer of files and database contents, followed by reconfiguration and verification on the target. The work is not a file copy alone. It covers consistent file and database backups taken from the same point in time, server configuration that matches the PHP and database versions EspoCRM supports, correct permissions on the application and data directories, corrected connection and site URL settings in the config file, a working cron entry for background jobs, and a test pass before users are cut over. The EspoCRM documentation on moving to another server describes the sequence, and the server configuration docs list the supported PHP, database and web server combinations you must match on the new host.
Effort is driven by three things. The first is customization: custom entities, layouts, formula scripts, extensions and any files under the custom directory all need to arrive intact and load cleanly, and each extension should be checked for compatibility with the target version. The second is the database engine. If you move from MariaDB to MySQL, the EspoCRM docs state that a MariaDB dump is incompatible with MySQL because MariaDB accepts default values on TEXT columns and MySQL does not, so those defaults must be removed from the dump file by hand before import. Confirm the exact MySQL version you will run, since EspoCRM requires MySQL 8.0 or newer. The third is cutover tolerance: how long users can be without the CRM, and whether you need a rehearsal on a copy before the final sync.
The open-source edition can be downloaded and self-hosted for free, so the cost of this work is labor and infrastructure rather than licensing. Expect one-time costs for planning, the migration rehearsal, cutover and verification, and recurring costs for the new servers, backups and maintenance afterward. If you hire a partner, ask for a written scope that names the source and target environments, the database versions on each side, how customizations and extensions will be inventoried and tested, the rollback plan if verification fails, and who performs the cutover and post-move checks.
What maps cleanly and what needs rework when moving EspoCRM
This table compares each part of a self-hosted EspoCRM instance with its counterpart on the new host and notes what must be reset or re-checked. Read the rows marked as rework first, because environment-specific values and external services are where a move most often breaks. Items that move as files or database content generally carry over, while anything tied to the old host's address, credentials or licenses needs confirmation before cutover.
| Item | Platform equivalent on the new host | Migration notes |
|---|---|---|
| Application files | Same EspoCRM version installed on the new server | Keep the version aligned with the source; confirm PHP and web server match the server configuration requirements before copying files. |
| Database records | Restored database on the new database server | Moving from MariaDB to MySQL needs manual removal of TEXT column defaults from the dump file; verify record counts after restore. |
| Custom entities and layouts | Carried in the custom directory and database metadata | Copy the custom directory with the application files and confirm layouts and entity definitions appear after restore. |
| Extensions and their licenses | Extension packages reinstalled on the new host | Confirm each extension and its license are valid for the new host before cutover; licenses may be tied to the instance. |
| Uploaded attachments | Files directory on the new server | Copy the data directory with correct ownership so attachments open; a database-only restore leaves attachments broken. |
| Scheduled jobs | Crontab entry on the new server | Scheduled jobs do not move with the files; recreate the cron entry for the web server user and confirm background jobs run. |
| Config file (database and site URL) | Rewritten config values for the new host | Database host, credentials, and site URL must be reset; a copied config pointing at the old host breaks login and links. |
| Mail and other environment settings | Outbound mail and external service settings on the new host | Mail server, sender addresses and API endpoints are environment-specific and must be re-entered and tested. |
| OIDC or LDAP authentication | Identity provider configured with the new site URL as redirect target | Update redirect and callback URLs at the identity provider; confirm the new host is trusted and test sign-in before users are moved. |
Documented tools for copying an EspoCRM instance
EspoCRM's move guidance is documentation-led, so the right path depends on your version, your extensions and whether you are moving the whole instance or only records. The cards below cover the documented options and what to confirm before choosing one.
File and database backup and restore
The most direct path is to copy the application files and the database dump together, then restore both on the new server. The two must come from the same point in time, or uploaded attachments and database rows will not match. Confirm in the docs which files and config entries must travel with the database, and whether your database engine on the new server matches the source. Check that the restored instance can reach its database and serve the correct site URL before cutover.
The command.sh backup and restore utility
Instances built with the installation script include a command.sh utility for backups, restores and upgrades. It suits teams whose current instance came from that script and whose new server will run the same Docker-based stack. Confirm that the target host meets the script's supported Ubuntu, Debian or Linux Mint requirements, and check the installation docs for the restore syntax and any version limits before relying on it. Do not assume it restores instances that were built by hand.
Fresh install followed by data restore
A clean install on the new server, followed by restoring the database and files, avoids carrying over an old web server, PHP or operating system configuration. The new install must match the EspoCRM version of the source instance, or the restore may fail or leave the schema out of step. Plan to verify the server configuration requirements for PHP, the database and the web server, and to recreate cron for background jobs, since cron is not restored with the files.
CSV import for record-level moves
CSV import moves records, not settings, layouts or extensions. It fits a partial move, such as bringing accounts and contacts into an instance that was configured separately. Import supports create-only, create-and-update and update-only modes, with duplicate matching on chosen fields. Plan the import order so that related records exist before they are linked, and confirm that reverting an import is available for the entity types you move.
Export Import extension for configuration and records
The Export Import extension is the documented route for moving records, settings and customizations between instances, and it is the option to examine when the target instance already has its own configuration. Confirm with the EspoCRM docs and the extension documentation that it supports the entities, customizations and files you need, and that it matches your EspoCRM version. Check whether an extension license is needed on the target instance before you plan the import.
Handling the MariaDB to MySQL dump incompatibility
The EspoCRM documentation states that a dump taken from MariaDB cannot be loaded into MySQL as-is, because MariaDB accepts default values on TEXT columns and MySQL does not. Before you import, you must remove those defaults from the dump file by hand. Treat this as a required step whenever the source is MariaDB and the target is MySQL, and plan it into the cutover window rather than discovering it during a failed restore. Confirm the exact target you will run first: the EspoCRM server configuration docs require MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15, alongside PHP 8.3 to 8.5. A mismatch on either side will block the move before the dump question even arises.
Start by locating the affected definitions. Open the dump in a text editor or search it for TEXT column definitions, then check whether any of them carry a DEFAULT clause. Remove only the default on those columns, leaving column types, nullability and the rest of the table definition unchanged. Keep a copy of the original dump so the edit can be reviewed or repeated. Record every table and column you changed, because that list becomes part of your cutover evidence and tells you where to look if a later problem appears.
Restore the cleaned dump into a non-production MySQL instance and point a test copy of EspoCRM at it, with the database host, name and site URL corrected in the config file. Then verify the move in two ways. Compare row counts for the main tables between the MariaDB source and the restored target, and investigate any difference before go-live. Next, open a sample of key records, such as accounts, contacts, opportunities and users, and check that fields, relations and attachments display correctly. Confirm the outcome with the people who use those records every day. Ask your database team to confirm the backup and restore procedure they will use in production.
Sequence for moving EspoCRM with a pilot, parallel run and cutover
This sequence moves a self-hosted EspoCRM to new servers or a new database in controlled stages, so the cutover is a rehearsed event with a verified fallback rather than a single risky switch. It ends with a source server kept for a retention period that you set.
Inventory the source server and its dependencies
Record the current EspoCRM version, operating system, web server, PHP version and extensions, database engine and version, file storage locations, cron entries and any custom files under the custom directory. DeployOpen checks these against the target versions in the EspoCRM server configuration docs, which list PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer or PostgreSQL 15. Done when you hold a written inventory that your team has signed off and that lists every extension licence to be transferred.
Build the target and restore a pilot
Provision the new server with the agreed web server, PHP, database and cron setup, then restore a recent file and database backup into it as a pilot. Correct the database connection and site URL in the config file for the new environment and set file permissions so the web server can write to the required directories. Done when the pilot instance loads, the admin can sign in and the background job runner executes from cron on the new host.
Rehearse the move with a copy of production data
Run the full move from a fresh copy of production data, including the database dump, any MariaDB to MySQL conversion, file transfer and configuration changes. If the source is MariaDB and the target is MySQL, the EspoCRM docs state that TEXT column defaults must be removed from the dump by hand, so the rehearsal should time and verify that edit. Record every manual step and its outcome. Done when a complete rehearsal runs without unplanned fixes and the runbook reflects what actually happened.
Run a short parallel period with the source frozen
Agree a read-only or freeze window on the source instance with the business owners, then run the target in parallel for a short, defined period to test real workflows against the copied data. Users should not enter new records on both systems during this period. Done when the agreed test cases pass on the target and any defects are logged, fixed and retested.
Take the final backup and cut over
Enable the freeze on the source, take a final file and database backup, restore it to the target and confirm record counts and key attachments match. Then change DNS to the new server and update the site URL in the configuration so links, email templates and integrations point to the new address. Done when the production hostname resolves to the target, the site URL is correct and the source is no longer accepting edits.
Verify logins, email, jobs and attachments
Test sign-in for representative admin, standard and portal users, confirm that outbound and inbound email work from the new host, check that scheduled jobs such as email processing and workflows run on their expected schedule, and open a sample of attachments and file-backed records. If single sign-on is configured, confirm the identity provider redirect also resolves to the new URL. Done when each check is recorded with a named owner and any failure has an agreed fix.
Decommission the old server after retention
Keep the source server and its final backup available for the retention period your organization sets, so the team can recover data or compare records if a problem appears after cutover. Once that period ends, revoke access, remove stored credentials and dispose of the backups according to your data retention policy. Done when you have a written confirmation of retention end, the source is shut down and the removal is logged.
What drives the cost and duration of an EspoCRM server move
This table lists the factors that change how much planning, rehearsal, cutover and validation an EspoCRM move needs, and how each one pushes cost or schedule. Read it to see which items in your environment will raise the quote and which questions to put to a partner or your own team before agreeing on scope.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Custom entities, layouts and formula scripts | Each custom entity, layout and Formula Script must be exported, checked against the new instance and retested, and scripts that reference other entities need more validation. | Document the Entity Manager and script inventory before the move and remove unused items. |
| Number of extensions and license checks | Each extension must match the target version, and licenses tied to the old instance may need re-verification before cutover. | List every installed extension, its version and its license owner in advance. |
| Database size and attachment volume | Larger databases and file stores lengthen backup, transfer, restore and integrity checks, and they extend the window in which the site is unavailable. | Clean up old attachments and temporary files, and measure the data directory before planning the window. |
| Database engine change | Moving from MariaDB to MySQL requires dump edits, such as removing TEXT column defaults, and extra test restores, which adds rehearsal time. | Keep the same engine where possible, or schedule several test restores to find dump issues early. |
| PHP and database version changes | Version changes add compatibility testing for the application, extensions and server configuration, and may require a separate upgrade step. | Confirm the target PHP and database versions against the EspoCRM server configuration docs before scoping. |
| Downtime tolerance | A short permitted outage needs a rehearsed cutover runbook, a final synchronized backup and a rollback plan, which costs more labor than a relaxed window. | State the acceptable outage window in writing so the cutover plan can match it. |
| Integration endpoints to repoint | Each external system that calls EspoCRM, such as mail, API clients, SSO or webhooks, needs new URLs, credentials and tests. | Inventory every integration and its owner, and agree who updates each endpoint. |
| Number of users to validate | Validation needs test cases for each role and team, plus sign-in checks for each authentication method, so more roles and users mean more testing time. | Limit validation to representative users per role and agree a written acceptance checklist. |
| Infrastructure (recurring) | New servers, storage, backups and monitoring carry ongoing costs after the move, separate from the one-time labor. | Ask for the infrastructure assumptions in the quote and compare them with the current footprint. |
| What to ask for in a quote | A quote should separate planning, rehearsal, cutover, validation and post-move support, and state the assumptions behind each. | Request a written scope listing the drivers above, the number of rehearsals and the acceptance criteria. |
What usually goes wrong when EspoCRM changes servers
Most failed EspoCRM moves are not technical surprises. They come from a short list of gaps: data captured at different times, settings that still point at the old host, file permissions, a missing scheduled job, and integrations nobody remembered. Each card below names one of these risks and the check that prevents it.
Files and database taken at different times
If the database dump and the file directory come from different points in time, records can reference attachments that do not exist, or attachments can exist with no matching record. Take both from a quiet window, ideally with the application in maintenance mode or with writes stopped, and record the time of each backup. After restore, open a sample of recent records with attachments and confirm they load. Ask your team to confirm how writes are paused in your environment before the copy starts.
Wrong site URL and database settings
The configuration file holds the database host, name, user and the site URL. If any of these still reference the old server, login may redirect to the old address, links in emails will point to the wrong host, or the application will fail to connect. Review every database and site URL value in the configuration file after copying it, and test login, a record view and an outgoing email link on the new host before pointing users at it.
Incorrect file ownership and permissions
EspoCRM writes to its data, cache and custom directories while it runs. If those directories belong to the wrong user after copying, the web server user cannot write, and errors often appear only when a user saves a record, uploads a file or changes a layout. Set ownership to the web server user and confirm write access to the writable directories as part of the cutover checklist, then test a save, an upload and a layout change.
Forgotten crontab entry
EspoCRM needs cron or a scheduled task for background jobs. On a new server, the crontab entry is not carried over automatically, so scheduled jobs, workflows, queued emails and some imports stop without any visible error on the login page. Add the entry for the web server user on the new host, then confirm that a scheduled job runs and that a queued email is sent. Keep the old server's entry disabled so two hosts do not run the same jobs against one database.
MariaDB dump left unfixed
A dump taken from MariaDB can contain default values for TEXT columns that MySQL does not accept. The documented fix is to remove those defaults from the dump file manually before importing it into MySQL. If the import fails, the move stops, and if someone edits the file in a rush, columns may be altered incorrectly. Check the dump for TEXT column defaults before import, keep the edited file under version control, and confirm the schema matches the source after restore.
Extensions, licenses and integrations left behind
Extensions and their licenses do not always move with the database, and integrations such as email, calendar, telephony, payment or webhook endpoints often hold the old host name in their own settings. Inventory every installed extension and its license status before the move, confirm each one works on the target version, and update each external callback or endpoint to the new address. Ask the vendor or your administrator to confirm license transfer rules for each extension.
Questions teams ask before moving EspoCRM to a new server
Can our own team move EspoCRM to a new server without a partner?
Yes, if your team has Linux administration, database and web server experience and a clear rollback plan. The documented move involves copying the file system and database, correcting the database connection and site URL in the configuration file, setting file permissions, and restoring the crontab so background jobs run. None of these steps is unusual for a sysadmin, but mistakes in permissions or the site URL are easy to make and hard to spot until users log in. Confirm that someone on your team has run this before, and that you can test on a copy of production first. The EspoCRM documentation on moving to another server is the right starting point for your own runbook.
What does the move need from our side before work starts?
Three things matter most: administrative access to the current and target servers, a maintenance window agreed with the people who use the CRM, and a named business owner who can approve the cutover and confirm that records look correct afterward. Access should include shell rights for file and database work, database credentials with dump and restore rights, and DNS or load balancer control if the hostname changes. Ask the business owner to decide what happens to data entered during the window, because users writing to the old instance during the copy can create gaps. Confirm these needs with your own change management process before scheduling.
How long does a server or database move take, and what drives the duration?
Duration depends mainly on the size of the database and the attachment files, the number of steps that must be verified, and how many environments need testing before cutover. A small instance with few files can be copied quickly, while a large one with years of attachments takes longer to transfer and check. Other drivers include the number of custom entities and extensions that must load on the new server, the need to match PHP and database versions, and how much of the process runs in a test environment first. Ask any provider for the timeline in writing and for the assumptions behind it, including data volume and the number of test cycles.
What should a quote for a server move include?
A useful quote lists each deliverable and who performs it: inventory of the current instance, file and database backup, target server configuration, permissions and crontab setup, configuration corrections, a test cutover, the production cutover, and a rollback plan. It should state which environments are in scope, whether the database engine changes, what verification is done after cutover, and what the client must provide. Ask for the fixed scope and timeline in writing, and check whether extensions, custom code or external integrations are included or excluded. DeployOpen does not publish a price list, so a quote follows from the written scope.
Is the MariaDB to MySQL change risky for EspoCRM?
It can be, but the risk is known and documented. The EspoCRM documentation states that a MariaDB dump is incompatible with MySQL because MariaDB supports default values for TEXT columns and MySQL does not, so those defaults must be removed from the dump file manually before import. If the dump is imported without this correction, the restore fails or behaves unexpectedly. Test the edited dump on a copy of the database, compare row counts and key records, and check the application logs after the first login. Confirm the MySQL version you target against the EspoCRM server configuration documentation before you choose it.
What happens after cutover, and who watches the new server?
After cutover, the most important tasks are confirming that scheduled jobs run, checking that email sends and receives, verifying user logins, and keeping the old instance available in read-only mode for a defined period so you can recover if needed. Background jobs depend on cron or a scheduled task, so a missing crontab entry is a common cause of quiet failures. Decide who monitors logs and backups after the move, and agree how long the rollback option stays open. Ongoing support, upgrades and testing can be handled by your team or by a retainer, and the support scope should be written down before go-live.
Do we need to move the database engine, or can we keep the current one?
Keep the current engine if it is supported and the move is only about hardware or hosting. Changing from MariaDB to MySQL is a separate decision that adds dump editing and extra testing, so make it only when you have a reason such as a standard your organization requires. Confirm the supported database versions in the EspoCRM server configuration documentation for the release you plan to run, since the supported list changes across major versions. Document the reason for the engine choice in your change record.
Who owns what during an EspoCRM rehosting
The client keeps the decisions that only they can make: which server or cluster the instance moves to, which database engine and version it runs on, the DNS and TLS changes that point users at the new site, and the cutover window. The client also supplies access to the source and target hosts, database administrator credentials for the dump and restore, and a named owner for the CRM data. Those data owners confirm which entities, custom fields, workflows and file attachments must survive the move and who signs off that the new instance matches the old one. Without that sign-off, a rehosting can be technically complete and still fail the business.
DeployOpen plans the move, rehearses it on a copy of the instance, and performs the configuration work inside the client's own infrastructure. That covers the file and database backups, file ownership and permissions for the web server user, corrections to the database host and site URL in the configuration file, the cron entry that drives background jobs, and the handling of the MariaDB to MySQL dump difference if the engine changes. Validation is run against a checklist agreed in advance, including logins, record access, email, scheduled jobs and attachments, and the result is documented so the client's team can operate the new host afterward. Confirm with DeployOpen which of these steps sit inside the fixed scope and which the client's team will run itself.
Every rehosting is a fixed-scope engagement. Scope, deliverables, the cutover plan and the acceptance criteria are written down and agreed before any work starts, and changes to them are handled in writing. Ask for the written scope to name the source and target environments, the backup and rollback approach, who performs each cutover step, and what happens if validation fails. Because the work runs in your cloud accounts, data centers or private networks, access is granted and revoked by your team, and the client keeps ownership of the resulting configuration and documentation.
How DeployOpen scopes and delivers an EspoCRM server move
DeployOpen plans and carries out the move of a self-hosted EspoCRM instance to new servers or a new database inside infrastructure you control. Each engagement starts with a written scope that names the source and target environments, the database engines involved, and the files and settings to transfer, so the cutover plan is agreed before any data moves.
How we scope
- We inventory the current server, PHP version, web server, database engine and version, and cron setup before agreeing the target.
- The written scope names the file and database backups, config corrections, and the MariaDB to MySQL dump check if that path applies.
- We confirm with you who owns DNS, certificates, backup storage and the cutover window, since these decide the timeline and cost.
How we build
- We build the target server to the documented requirements, then restore a test copy of files and database to verify it before production.
- We correct the database connection and site URL settings in the config file, set file permissions, and configure the crontab for background jobs.
- We test logins, record access, email, scheduled jobs and file attachments on the new server, then rehearse the cutover steps.
How we hand over
- You receive a runbook covering the final backup, DNS switch, post-move checks and rollback steps used during cutover.
- We document the server layout, config keys changed, cron entries and backup schedule so your team can run the instance afterward.
- Handover is complete when your administrators have run a restore test and confirmed the acceptance checks listed in the scope.
How we support
- Fixed-scope engagements end at the agreed handover, and any further changes are quoted from a new written scope.
- Ongoing support, upgrades and continuous testing are available as a retainer for teams that want the instance maintained after the move.
- Before quoting, ask us to confirm the support hours, response terms and backup restore testing included in the retainer.
