dotCMS Backup and Restore Guide for Stable Deployments

A website is more than a bunch of files. It is the first thing people see when they interact with your brand. For any digital business, it must work smoothly no matter where it is running. Moving a dotCMS setup from one machine to another is something most teams do regularly, especially when development, testing, and deployment happen on different systems.

This is where dotCMS backup and restore become critical.

Even a small mistake during migration, such as a missing folder or corrupted volume, can break the entire site.  

Below is a practical dotCMS backup guide that explains how to back up your dotCMS files and restore them on any machine with confidence.

Why is Backup & Restore important in dotCMS?

Let’s say your team is preparing to roll out a big update, new templates or refreshed content. Everything is ready, and then one tiny misconfiguration suddenly takes your dotCMS environment down. If you don’t have a backup, that downtime can quickly turn into a major setback, which clearly highlights why dotCMS environments require a reliable backup and restore strategy for business continuity.

In dotCMS, your content, users, workflows, and relationships are stored in the database. Meanwhile, all file-based resources, such as themes, assets, containers, and plugins, are stored in the dotcms_cms-shared volume when running with Docker. This shared volume plays a crucial role because it holds so much of what defines your site.

Having a clear, reliable dotCMS backup and restore process gives your team stability, protects you from losing important data, and makes recovery easier when something goes wrong.

Every major update comes with some level of risk. With a proper backup in place, you always have a safe rollback option if something doesn’t go as planned. These dotCMS backup best practices are essential for long-term stability.

• Easy migrations between machines or environments

If you're switching from Windows to macOS or from Development to Staging or from On-Prem to the Cloud. Backups give you a clean, portable snapshot of your entire dotCMS setup.

• Faster recovery from unexpected failures

If your Docker volume becomes corrupted or the system crashes, restoring from a backup quickly restores everything and reduces downtime.

• Faster onboarding for new developers and new environments

With these, new team members or servers can now easily start with the same setup. No mismatched environments, no wasted time to set up. This makes it easier to begin with dotCMS even for distributed teams.

Steps for Source Machine

1. Find the dotCMS Volume

Open PowerShell or Command Prompt, and run:

docker volume ls

You will get an output like this:

DRIVER  VOLUME NAME 
local   dotcms_cms_shared
local   dotcms_opensearch-data

You need to focus on dotcms_cms-shared, where dotCMS stores your assets, templates, and other configuration files.

2. Create a Backup of the Volume

Go to any directory where you would like to store the backup, and run:

docker run --rm -v dotcms_cms-shared:/source -v ${PWD}:/backup alpine tar czf /backup/dotcms_shared_backup.tar.gz -C /source .

This command compresses the entire /source volume and produces dotcms_shared_backup.tar.gz in this directory.

This file is the full dotCMS backup and restore archive of all shared resources.

Steps for Target Machine

1. Transfer the Backup File

Move the dotcms_shared_backup.tar.gz file to the system where you are planning to restore dotCMS.

2. Stop the existing dotCMS container and clean up old volumes

Go to your dotCMS project folder and run:

docker compose down
docker volume rm dotcms_cms-shared dotcms_opensearch-data

This will remove old data so new data can be restored cleanly.

3. Verify the Environment is Clean

Run:

docker ps -a
docker volume ls

Ensure that no dotCMS containers or volumes remain.

4. Create a New Empty Volume

Create a fresh shared volume:

docker volume create dotcms_cms-shared

5. Place the Backup File in the Project Directory

Move the backup file dotcms_shared_backup.tar.gz into the same directory as your docker-compose.yml file.

6. Restore the Backup into the Volume

Run the restore command from Terminal:

docker run --rm -v dotcms_cms-shared:/target -v $(pwd):/backup alpine sh -c "cd /target && tar xzf
/backup/dotcms_shared_backup.tar.gz"

docker run --rm -v dotcms_cms-shared:/target -v $(pwd):/backup alpine sh -c "cd /target && tar xzf /backup/dotcms_shared_backup.tar.gz"

This will extract all backed-up resources into the new volume.

7. Verify the Restore Was Successful

Check if the assets folder exists and contains files:

docker run --rm -v dotcms_cms-shared:/target alpine ls -R /target/assets/

If you see directory listings, your dotCMS backup and restore process is successful.

8. Start dotCMS

Bring dotCMS back online by running:

docker compose up -d

Once it starts, your dotCMS instance will load with all your previous themes, assets, and other site resources exactly as they were.

Conclusion

A website plays a big role in how people view your brand. If your site is slow, keeps breaking, or behaves inconsistently, it can damage trust, and if this persists, you will lose customers. That’s why making sure your dotCMS setup is stable, easy to move, and simple to restore through dotCMS backup and restore is not just a technical task; it’s a smart move for your business. 

When you have a clear and reliable dotCMS backup guide, you can make changes, scale up, and try new things without worrying about your digital presence.

A solid backup workflow also helps your team work better. Developers spend less time fixing environment issues, testers get consistent data to work with, and deployment teams can roll out updates without fear of unexpected problems by following proven dotCMS backup and restore practices.

Overall, this means less downtime, better teamwork, and a smoother development process. Backups also make it easier to switch to new infrastructure, move to different hardware, or bring new team members on board because you always have a reliable copy of your site ready to go, whether managed internally or with support from teams that hire dotCMS Developers.

By using this guide, your team can:

• Move between environments without friction.
• Recover quickly when something breaks.
• Get new developers set up faster.
• Perform updates without fear of downtime.

All while keeping your website’s design, content, and features running smoothly. A good dotCMS backup and restore strategy isn’t just about keeping your data safe; it’s about protecting your brand’s continuity, performance, and reputation.