Best Practices for Migrating Frappe Apps Versions Using Custom Docker Images and Docker Compose

Hello everyone,

I’m working with a custom Docker Compose setup to manage Frappe and ERPNext environments. I’m looking for guidance on the best practices for migrating between different versions of ERPNext or Frappe apps, specifically when upgrading or downgrading versions using custom Docker images.

Here are the key scenarios I’m working with:

  1. Downgrading ERPNext Versions:
    What’s the safest and most reliable way to downgrade ERPNext in a Docker environment? For example, if I need to revert from v15.36.1 to v15.34.0, how can I achieve this without risking data integrity or causing issues in the database and the environment?
  2. Upgrading ERPNext to Newer Versions:
    When upgrading to newer versions (e.g., moving from v15.34.0 to v15.36.1 or newer), what steps should I follow to ensure a smooth transition? How can I manage the migration of database schemas and app changes without disrupting the existing setup?
  3. Switching Between Branches and Tags:
    How do you efficiently switch between different branches or tags (e.g., from version-15 to a specific tagged release like v15.34.0) in a Docker Compose-based setup?
  • What are the implications for the database and app structure when switching between tags or branches?
  • Are there any tools or workflows that can simplify this process?
  1. Handling Versioning and Rollbacks:
    What is the best strategy for rolling back an upgrade if something goes wrong? How can I properly tag Docker images and manage container snapshots to quickly revert to a stable version?
  2. Database Migrations and Backup/Restore Practices:
    When performing upgrades or downgrades, what are the recommended practices for handling database migrations?
  • Should I always create a database backup before switching versions?
  • How can I ensure that the database schema is consistent with the app version when downgrading or upgrading?
  1. Managing Multiple Environments:
    How can I effectively manage multiple environments (e.g., production, staging) with different versions of ERPNext/Frappe using Docker Compose? Any recommendations on handling isolated setups, while still allowing for easy upgrades/downgrades?

Any insights or advice on how to safely and effectively manage version upgrades or downgrades for Frappe and ERPNext using Docker Compose would be highly appreciated. I’m particularly interested in understanding how to handle migrations and version management in production environments.

Thanks in advance!

1 Like

Additionally, I want to install the apps based on a specific version tag. When I used branches like develop or version-15, they installed the latest version, v15.36.1, which contains several bugs. For example, I encountered issues where I couldn’t create purchase orders or invoices, whereas these functionalities worked fine in a previous version like v15.34.1.

Here’s the JSON I passed to the image in Base64:
[
{
“url”: “GitHub - frappe/erpnext: Free and Open Source Enterprise Resource Planning (ERP)”,
“branch”: “version-15”
}
]

OR

[
{
“url”: “GitHub - frappe/erpnext: Free and Open Source Enterprise Resource Planning (ERP)”,
“branch”: “develop”
}
]

However, using these branches installs the latest versions, which are buggy. Instead, I want to specify a version tag to install an exact, stable version.

For example, this is what I want to do:

[
{
“url”: “GitHub - frappe/erpnext: Free and Open Source Enterprise Resource Planning (ERP)”,
“tag”: “v15.34.1”
}
]

1 Like
  1. You cannot downgrade. You can only backup and restore if anything goes wrong. Fix patch and upgrade.
  2. For erpnext, take backup, change image tags, re create containers and run migrate. If anything goes wrong report/fix patch and restore backup for time being. Backup can be replicated dataserver which gets switched or simple dump and restore. Have a cron for backups.
  3. You can only switch to newer tags or you’ll have to restore old data for older tags. Don’t use branches or you’ll not have specific version, you’ll get the latest version from the branch. To migrate run the bench migrate command as task or job. You can re-migrate same version and nothing will really change.
  4. No rollback, only roll forward.
  5. Small db use dump. Large db use snapshots. For files use restic for differential backup.
  6. Check custom_containers/docs/docker-swarm.md at main · castlecraft/custom_containers · GitHub create as many stacks as the number of separate benches required. For kubernetes create as many helm release as number of benches required.

Check how I create image: .gitlab-ci.yml · main · castlecraft / CEPL ERPNext Images · GitLab all files used in script apps.json, build.env etc are part of same repo.

In case of apps completely in your control, you can design the schema in such a way that you can have least or no downtime.

4 Likes

I’m building a custom Docker image and deploying it using Portainer’s stacks. When I specify the tag version in the JSON file, the image still pulls the latest development version, like “Version 16.0.0-dev,” as shown below.

Additionally, it’s difficult to determine which versions of Frappe, ERPNext, HRMS, CRM, and other Frappe apps are compatible with each other. A 10-minute video explaining how to handle this smoothly and ensure version compatibility would be incredibly helpful for the community and future development.

image

image

One more question: When updating to a newer version tag, where should I run the bench migrate command? Should it be executed in the “create-site-1” container, or do I need to SSH into each container individually and run the command? I’ve tried several approaches without success so far :sob:.

I updated the JSON file to use the branch key instead of tag, and the installation is now working correctly by specifying the app version instead of the branch name! :slight_smile:

image

image

The next challenge is finding a smooth way to handle updates and migrations in Portainer stacks when new features or patches are released for the frappe apps including ERPNext, HRMS, and to install and uninstall apps from existing running containers, I tried to add the bench command to the create-site container with not success.