How the EspoCRM Docker upgrade works and when to run it
If your EspoCRM runs in containers and a newer release is out, the documented Docker Run upgrade is a container swap, not an in-place patch. According to the EspoCRM Docker installation documentation, the procedure pulls the latest mariadb and espocrm/espocrm images, stops and removes the espocrm, espocrm-db and espocrm-daemon containers, and starts them again with their original configuration. Your data lives in the volumes and settings you attached at first run, so those must be kept identical. Before you touch anything, record the exact run commands, environment variables, network names, port mappings and volume names you used, because the recreated containers only match the old ones if you reproduce them. EspoCRM's Docker installation guide is the reference for the steps.
Teams usually upgrade for three reasons: security fixes, extension requirements and access to new features. Extensions in particular can refuse to load on an older core, so an upgrade may be forced by a module you depend on. Major releases need more planning than the container swap suggests. The 9.0.0 release dates from January 20, 2025, and 10.0.0 from July 2, 2026, according to the EspoCRM releases page. A move from 9.x to 10.x changes what custom code and extensions must support, and the PHP runtime bundled with the target image must satisfy the new version's requirements. Confirm the PHP version, the removed APIs and extension compatibility for your target release before you pull anything.
The supported path is the documented steps run deliberately, not the administration UI. EspoCRM's security guidance notes that upgrading through the UI is disabled by default as of version 10.0, so plan for command-line execution of the upgrade process. Take a full backup of the database and the data volume first, and rehearse the upgrade on a copy of the instance with the same image tags, extensions and custom files. Confirm with your vendor or your own tests that the rehearsal restores cleanly and that the daemon and cron jobs come back. Run the upgrade in a window where users can be paused, and keep the previous image tag so you can recreate the old containers if verification fails.
What changes in EspoCRM 10 that affects a Docker upgrade
This table lists the changes in EspoCRM 10 that affect a containerized upgrade, what each one does to your stack, and what you must check before running the Docker Run procedure. Read it before you pull any image, because several rows change the order of work. The main takeaway is that the image tag and the PHP and database versions must be confirmed together, not after the containers are recreated.
| Change | Impact | Action needed |
|---|---|---|
| Major version jump from 9.x to 10.x | EspoCRM 10.0.0 was released July 2, 2026, after 9.0.0 on January 20, 2025. Moving from 9.x crosses a major boundary with more changes than a minor release. | Confirm your current version, then review the sibling EspoCRM 9 to 10 upgrade page for removed APIs and extension compatibility. |
| UI upgrade disabled by default | Starting with version 10.0, upgrading through the web interface is disabled by default, so the Docker container cannot be upgraded from the admin screen. | Plan the upgrade through the command line procedure your deployment uses, and confirm how your team will run it. |
| PHP version in the image | The server docs list PHP 8.3 to 8.5 as supported. An image built on an unsupported PHP version will not meet the requirement. | Check the PHP version of the image you intend to pin before pulling it, and keep the list of PHP extensions your instance needs. |
| Database version | The server docs list MariaDB 10.6 or newer, MySQL 8.0 or newer, or PostgreSQL 15. The Docker Run procedure also pulls a current mariadb image. | Confirm the database engine and version in the running stack, then check that the pulled database image meets the minimum. |
| Unpinned 'latest' tag | The Docker Run procedure pulls the latest espocrm/espocrm and mariadb images, so the upgrade lands on whatever version is current at pull time. | Confirm which exact EspoCRM and MariaDB tags you will pin, record them, and test them in staging before production. |
| Patch releases after 10.0.0 | Version 10.0.10 was released October 14, 2026, so a fresh pull may bring a different patch level than a test run. | Compare the tag you tested with the tag you deploy, and check the release notes for the version you pin. |
Preparing the EspoCRM Docker upgrade before pulling images
A Docker upgrade replaces containers, but the data lives in volumes and the behavior lives in configuration and custom code. Each of the checks below protects one of those, so you can roll back if the new image does not behave as expected.
Verified backup of database and volumes
Take a backup of the database and the file volumes before any image is pulled, then confirm that it can be restored. The installation script includes a command.sh utility that supports backups, restores and upgrades, so confirm which mode your team uses and whether it covers both the MariaDB data and the EspoCRM data directory. A backup that has never been restored in a test is a hope, not a rollback plan.
Inventory of images and container configuration
Record the image tags currently running for espocrm, espocrm-db and espocrm-daemon, along with every environment variable, port mapping, volume mount and network each container receives. Recreated containers only keep what you pass again, so a missing variable or changed mount can silently change behavior. Store this inventory with the change record so the team can rebuild the containers exactly.
Extension and custom code review
Review every installed extension and every file in the custom directory against the version you plan to run. Extensions declare the EspoCRM versions they accept, and custom code that uses deprecated backend or frontend APIs can break after the upgrade. Identify which items need a vendor release or a code change before the window opens, not during it.
Staging copy from the same images and data
Build a staging stack from the same image tags and a recent copy of the production database and volumes. Run the upgrade there first, then test logins, scheduled jobs, email, integrations and the custom workflows your teams depend on. Keep the staging configuration close to production so that results carry over.
PHP and database version checks
Confirm that the target image provides the PHP version and the database engine the release requires, and that the database container matches the versions your current data expects. The server configuration docs list PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15. Check the image you intend to pull rather than assuming the previous tag still applies.
Maintenance window and named rollback owner
Agree on a maintenance window with the users who will be affected, and name one person who has authority to stop the upgrade and restore the backup. Write down the rollback steps before the window starts, including how to restore the previous image tags and the database. Without a named owner, teams often hesitate at the point where a quick decision matters most.
The Docker upgrade sequence with checks and rollback points
This sequence moves a containerized EspoCRM instance to a new image tag while keeping the data volumes intact, with a verification gate and a rollback point after each risky change. The output is a running upgraded instance and a written record of what was checked at each stage.
Freeze changes and confirm the backup restores
The client's administrator stops all configuration edits, scheduled imports and bulk record changes, then takes a fresh backup of the database and the EspoCRM data volume. Someone who did not create the backup restores it into a separate test environment and logs in to confirm that records, attachments and users are present. This step is complete when the restore test has passed and the backup files are stored outside the host being upgraded. This is the first rollback point: if the backup does not restore, the upgrade does not start.
Record current image digests and container configuration
Capture the running image digests for the espocrm, espocrm-daemon and mariadb containers, along with the exact tag each one uses. Export the environment variables, port mappings, network settings, volume mounts and any reverse proxy or TLS settings from each container, or from the Compose file if you use one. Store this record with the backup so the same configuration can be recreated. The step closes when the team can state which tag and digest is currently running and where every volume is mounted.
Rehearse the upgrade in staging first
Build a staging stack from the production backup and the recorded configuration, then run the full upgrade sequence against it. Check that the target version runs its own database migration without errors, that custom code and extensions still load, and that the daemon starts. Staging is also where you confirm the target PHP-dependent behavior and extension compatibility for your version. The step is complete when staging passes every check in the later steps with no unresolved errors in the logs.
Pull the pinned target images
On the production host, pull the espocrm, espocrm-daemon and mariadb images at the specific tags chosen in the staging run, not at a floating latest tag. Record the new digests immediately after the pull so the exact images can be identified later. Keep the old images on the host, because they are needed for a rollback. The step is done when all three pulls succeed and the new digests are written to the change record.
Stop and remove containers without deleting volumes
Stop the espocrm, espocrm-daemon and espocrm-db containers, then remove the containers only. Do not run commands that delete named volumes or bind-mounted data directories. Confirm with a volume listing that the data volumes still exist and that their sizes are unchanged. This is a risky step, so the rollback point stands: if the database was not migrated, the old image tags can be restarted against these preserved volumes. If anything is missing, stop and restore from backup.
Recreate containers with the original configuration
Start the database container first, then the espocrm and espocrm-daemon containers, using the same environment variables, network, ports and volume mounts recorded earlier. Update only the image tag to the pinned target. Watch the startup logs until the application reports that it is serving requests. This step is complete when all three containers show as running and the application responds on its configured address. Because the database schema may now have been migrated, record the time of this step in the change log, since rollback after this point means restoring from backup.
Confirm the daemon and scheduled jobs run
Check that the espocrm-daemon container is running and that the background job process is active. Confirm that scheduled jobs, including the cron or scheduled task that EspoCRM requires for background work, execute on their normal cycle and do not accumulate failed entries. Review the job queue and the application log for repeated errors. The step is complete when queued jobs drain normally and no new failures appear across a full scheduled cycle.
Run login, record, email and job checks
Run a scripted checklist as a named test user, and as an administrator, covering login, opening and editing a record in each critical entity, creating a related record, uploading an attachment, sending a test email and running one scheduled job. Compare results with the expected outcomes from the pre-upgrade staging run. Any failure either gets fixed and retested or triggers a rollback decision. The upgrade is accepted only when every check passes and the outcome is signed off by the business owner. If the database was migrated and a failure cannot be resolved, restore from the verified backup.
Docker Run or Compose: how the recreate step differs
With Docker Run, EspoCRM is started from individual docker run commands, one each for the espocrm, espocrm-db and espocrm-daemon containers. The documented upgrade pulls the latest mariadb and espocrm/espocrm images, then stops and removes those three containers and runs them again with their original configuration. Nothing in the image pull changes your data, but the recreate step depends on every flag matching what was used the first time.
- Original commands: Locate the exact
docker runcommands used at install time, including network, port, volume and environment flags, before you remove anything. - Image pull: Pulling the latest tags means the version you land on is whatever the registry currently serves, so confirm the target version in the release notes first.
- Flag drift: A single changed port mapping, volume path or environment value on re-run can point EspoCRM at an empty database or a new file directory without any error at start-up.
- Container names: The three containers must keep the names
espocrm,espocrm-dbandespocrm-daemon, because the documented procedure assumes those names. - Database container: Confirm the database volume is mounted at the same path as before so the existing data is reattached.
Before removing anything, record the full command for each container and check that the volumes it references still hold your data.
With Docker Compose, the compose file records the image tags, service definitions, named volumes and environment file that EspoCRM runs with. The upgrade pins the image tags in that file, pulls the services, and recreates them while named volumes and the environment file stay in place. The file is the record of your configuration, so most of the risk moves to whether the names in the file match what is actually running.
- Pinned tags: Set the image tags in the compose file to the target version rather than relying on a floating tag, so the upgrade is explicit and repeatable.
- Service names: Confirm the service names in the file match the containers already running, since a mismatch can create a parallel stack instead of replacing the old one.
- Volume names: Check that the named volumes in the file match the volumes that hold your database and files, because a renamed volume starts empty.
- Environment file: Keep the environment file unchanged across the recreate, and compare its values with the previous file before running the update.
- Pull and recreate: Pull the services first, then recreate them, so a failed pull does not leave you with stopped containers.
Before you pull, run the compose listing command and compare the project, service and volume names with the file you plan to use.
The two methods reach the same outcome, but they keep configuration in different places. Docker Run keeps it in the shell history or a script you wrote at install time, and Compose keeps it in a versioned file. Which one applies to you depends on how your installation was built, and the recreate step should match that method rather than mixing both.
- Where the configuration lives: Docker Run relies on commands you must recover, while Compose relies on a file you can review and store in version control.
- Repeatability: A Compose upgrade can be reviewed as a diff between two files, which makes unintended changes easier to spot.
- Mixed setups: Containers started with Docker Run and later managed by Compose can carry names or volumes that the file does not describe, so confirm which method created each container.
- Rollback inputs: Keep the previous image tag and configuration so you can restore the earlier state if the new version fails.
- Staffing: Confirm which person on your team owns the commands or file, since an upgrade run by someone unfamiliar with the setup is where flag and name errors usually happen.
Identify how the existing containers were created before you choose a procedure, and write that answer down with the upgrade plan.
What makes an EspoCRM Docker upgrade take longer
This table lists the factors that stretch an EspoCRM Docker upgrade from a routine image swap into a planned project. Read each row as a question to answer about your own instance before you set a window. The main takeaway is that custom code, extensions and an untested restore path usually cost more time than the image pull itself.
| Driver | Why it matters | What to check |
|---|---|---|
| Custom entities and layouts | Entity Manager changes and custom layouts are stored in the instance and must still render and save correctly on the new version. | Count custom entities, layouts and formula scripts, and test each one in a staging copy of the same volumes. |
| Extensions and acceptable versions | An extension that does not declare support for the target version can block the upgrade or break screens after it. | Compare each installed extension's acceptableVersions range with the target version and confirm the vendor release exists. |
| Custom code in the custom directory | PHP hooks, custom controllers and overrides depend on internal APIs, so they are the most likely source of errors after an upgrade. | Review everything under the custom directory and any API before-save scripts against the release notes for the target version. |
| PHP version in the image | The target version may require a newer PHP runtime than the image you run now, and extension modules may need reinstalling. | Confirm the PHP version in the target image against the EspoCRM server configuration requirements before pulling. |
| Database and file volume size | Backup and restore time grows with data and file volumes, and a slow restore extends the rollback window. | Measure the size of the database volume and the files volume and time a test restore on the same hardware. |
| External file storage, reverse proxy and TLS | Changes to container networking, ports or certificate paths can break access even when EspoCRM itself starts cleanly. | Record the proxy configuration, certificate mounts and any external storage settings, and retest login and file access after the upgrade. |
| WebSocket daemon and background jobs | The espocrm-daemon container and scheduled cron jobs must restart on the new version or real-time updates and queued work stop. | Confirm the daemon container is recreated with the same configuration and that background jobs run after the upgrade. |
| Number of users in the test cycle | More users means more roles, teams and workflows to test, and more people who must sign off before go-live. | List the user types, roles and workflows that matter most and confirm who will run the acceptance tests. |
| Tested restore path | Without a restore that has been rehearsed, a failed upgrade can leave the team deciding under pressure whether to roll back. | Confirm that a backup of both database and files has been restored to a separate host and that the team knows the rollback steps. |
How to test the upgraded stack and roll it back if it fails
A tested Docker upgrade starts in staging, not production. Build a staging stack that uses the same image tags you plan to deploy, restore a recent copy of the production database and files into it, and run the upgrade exactly as you will in production, including the same espocrm, espocrm-daemon and espocrm-db containers and the same volumes. Then check the things users depend on: administrator and standard user logins, role-restricted views, record creation and updates on your most-used entities, and email sending and attachment upload and download. Confirm that scheduled jobs run and that the daemon is serving real-time updates. Test each extension you rely on, because a container upgrade does not confirm that an extension still loads under the new version. Record what passed and what failed so the production go or no-go decision rests on evidence.
Rollback depends on one question you must answer before the production run: did the new version change the database schema? Keep the previous image tags written down, and keep the old volumes or a verified backup taken immediately before the upgrade. If the schema did not change, reverting usually means recreating the containers with the previous tags against the same configuration. If it did change, an older image may not run correctly against the migrated database, so plan to restore the database from the verified backup and redeploy the previous tags. Test that restore in staging before you rely on it. Confirm the release notes for the target version on the EspoCRM releases page and with your own test results.
After any upgrade, reverify the security settings that a new deployment can silently change or leave unchecked. Confirm that administrators still use separate accounts for daily work, that two-factor authentication is enforced for the roles that require it, that IP restrictions still match your network, and that password recovery remains disabled for admins. Check the security guidance in the EspoCRM security documentation against your current settings and log the result. A successful functional test does not show that these controls still apply, so treat this check as part of the upgrade acceptance, not an optional follow-up.
What buyers ask before hiring help with an EspoCRM Docker upgrade
What does an EspoCRM Docker upgrade cost?
The cost is set by the written scope, so there is no fixed price for every instance. The main drivers are the number of extensions to check, how much custom code sits in the custom directory, the size of the database, how many environments need to be upgraded (staging and production at minimum), and how many test cycles the business wants before go-live. The one-time costs are the assessment, the staging rehearsal, the production cutover and the post-upgrade fixes. Recurring costs only appear if you add a support or upgrade retainer. Ask any provider for a quote that lists each of these items separately and states what is excluded, such as extension licensing you need to buy yourself. DeployOpen does not publish a price list; a quote follows from the written scope.
How long does an EspoCRM Docker upgrade take?
Duration depends on what has to be verified before the containers are swapped, not on the swap itself. The timing is usually set by extension compatibility checks, the time needed to restore and test a copy of production data, how many custom entities, layouts and formula scripts need review, and how quickly your team can run acceptance tests and sign off. Your own change windows and approval steps also matter. Ask the provider for a schedule with named milestones tied to your decision points, and confirm which work happens in staging before any production change is planned.
What access and people does an EspoCRM Docker upgrade need from our side?
The work needs a small set of inputs from your side before it starts. Expect to provide:
- Access to the Docker host or orchestration platform, with rights to pull images and manage the
espocrm,espocrm-dbandespocrm-daemoncontainers - A current, restorable backup of the database and the files volume, plus confirmation that the restore has been tested
- An administrator account for the instance, ideally a dedicated one, and read access to the compose file or run configuration
- A test user group that covers each role, team and portal user type
- A named decision maker who can approve the staging results and the production cutover window
Without these, the provider cannot confirm the upgrade path or prove that data is intact afterward.
Can our internal team upgrade EspoCRM on Docker without outside help?
Yes, a team with Docker experience and a clear test plan can do the container steps itself. The official Docker documentation describes an upgrade that pulls the latest images and recreates the containers with their original configuration, so the mechanics are not the hard part. The harder work is the surrounding checks: confirming extension compatibility, reviewing custom code against the target version, verifying PHP and database prerequisites, and running acceptance tests with real users. Teams that have no one to own those checks, or no spare staging environment, usually find an external review or a fixed-scope engagement reduces risk. Compare the internal effort you would need to commit against a written scope from a provider.
How do we avoid losing data when the containers are replaced?
Data survives a container swap only when the database and the files are kept on persistent storage and the new containers are started with the same volumes and configuration. The official Docker upgrade runs the containers again with their original configuration, which is why the volumes and environment settings must be recorded before anything is pulled. Take a full backup of the database and the files volume, store it outside the host, and test a restore on a separate machine. Confirm that the espocrm-db container uses the same data path after the swap. Keep the old images and configuration until the new version has passed acceptance tests.
What happens if an EspoCRM Docker upgrade fails partway through?
A good plan defines the rollback before the upgrade starts. If the new containers fail to start or the application misbehaves, the usual response is to stop the new containers, restore the database and files from the tested backup, and start the previous image tags with the saved configuration. This only works if the previous image versions are still available and the backup has been restored successfully in rehearsal. Ask the provider to document the rollback steps, the decision point at which rollback is chosen, who makes that call, and how users are informed. Also confirm whether post-upgrade fixes are inside the fixed scope or handled separately.
Does the upgrade cover extensions and custom code as well as the containers?
It should, if the scope says so. The container steps are only part of an EspoCRM upgrade. Each installed extension needs a version that supports the target release and the PHP version it requires, and custom code in the custom directory must be tested against the new version. Your written scope should list every extension, custom entity, layout, formula script and integration that is in scope, and state which ones you will test or fix. Anything left out, such as third-party extensions without a compatible release, should appear as an open item with an owner. Check the scope line by line before signing.
Which EspoCRM and PHP versions should we confirm before a Docker upgrade?
Confirm the target EspoCRM version and its PHP and database requirements against the official documentation before you pull any image. The server configuration docs list PHP 8.3 to 8.5, with MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15 as supported databases. Check that the image tag you plan to use matches the version you have tested, and confirm that the release notes do not list breaking changes for your customizations. Ask your provider to show which versions were tested in staging and to record them in the upgrade report.
How DeployOpen works on this
DeployOpen is a Chainscore Labs company that plans, implements, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. For a Docker-based EspoCRM upgrade, we start from your current image tags, volumes, environment file and database container, then agree the work in writing before any change is made to a running instance.
How we scope
- Inventory the running containers, image tags, named volumes and environment settings for espocrm, espocrm-db and espocrm-daemon
- Confirm the target EspoCRM version and the database version it requires before any pull is planned
- Record the agreed scope, deliverables and timeline in writing; engagements are fixed-scope
How we build
- Rehearse the upgrade on a copy of the instance with a restored backup and the same volumes
- Test custom entities, layouts, formulas, extensions and integrations against the target version
- Document each Docker Run or Compose step, with the rollback path and the backup taken before it
How we hand over
- Deliver a runbook with the exact image pulls, container recreation steps and post-upgrade checks
- Walk your operators through the verification list, including login, background jobs and email
- Leave the backup, restore and rollback records in your own environment for audit reference
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after the handover
- Review each new EspoCRM release against your extensions and custom code before the next upgrade
- Keep your upgrade documentation current when images, database versions or configuration change
