Upgrading Document Engine

We recommend always running the latest version of Document Engine, as each version introduces new features and performance improvements. Additionally, we always verify that the release process is seamless when upgrading to the newest version from the last major release. If you’re using an older version, make sure to upgrade one major version at a time.

Example: If the latest version is 1.6.1 and you’re running 1.4.4, upgrade to 1.5.x first, and only then to 1.6.1.

We recommend always going through the upgrade process in a non-production environment first.

The process of upgrading to a new version of Document Engine varies depending on whether you’re running a single instance or multiple instances.

Single-Node Deployment

In a single-node deployment, shut down your Document Engine instance and start a new one using the new Docker image.

Multi-Node Deployment

In a multi-node setup, the simplest approach is to scale down your Document Engine deployment to only one instance and then upgrade it. Then, once it’s up and running, start the other instances with the new version.

If you can’t accept downtime, you can also follow a more complex upgrade scenario:

  • Drain traffic from a single instance and make sure that no requests are directed to it.

  • Upgrade the instance to a new version. Don’t direct traffic to that instance yet.

  • Once that instance is up and running, continue with other instances after you reach a number that’s sufficient for serving your user traffic. Note that, at this moment, all users will still be served by instances running the old version.

  • Switch all traffic to instances running the new version.

  • Continue with the upgrade for the rest of the instances. Once an instance is running the new version, you can immediately add it to the group serving the user traffic.

While this approach is more complex and requires a deployment infrastructure that provides control over which instances are serving user traffic, it allows you to upgrade without downtime.

Database Migrations

When targeting zero-downtime upgrades, especially if database migrations are involved, it’s crucial to ensure that both the new and previous versions of Document Engine can work with the updated database schema. Here are some considerations we make when handling database migrations in Document Engine:

  • Backward-Compatible Migrations — We have an internal policy to avoid backward-incompatible migrations if possible. This means the new database schema is compatible with both the old and new versions of Document Engine. If we do introduce a breaking migration, we’ll clearly indicate it as such in the appropriate migration guides and provide you with recommendations on how to minimize downtime.

  • Locking and Performance — During a migration, the database might need to briefly lock specific tables to apply schema changes. This should be unnoticeable, but there might be a slight performance impact, especially when backfilling data or building indexes. As with backward compatibility, we’ll clearly communicate when this needs to be considered in our migration guides.

  • Testing and Backup — Always perform migrations in a staging environment first. If this isn’t possible, ensure you have a backup of the production database and plan for a maintenance window to mitigate any potential issues.

  • Model Data Compatibility — Changes in our document data model, such as updates to how annotations are stored, need careful handling to avoid issues with migrated documents not opening in the old version of Document Engine. We aim to avoid breaking changes in the document data model, but it’s important to test thoroughly if you aren’t following our recommendation to always update one major version at a time.