Skip to main content

Medplum v4.0.0 Upgrade Notice

· 4 min read
Cody Ebberson
Cody Ebberson
Medplum Core Team

We've heard many success stories from enthusiastic early adopters who have smoothly upgraded to v4. Thank you all for your support and your feedback in this process!

However, we've identified an issue affecting some Medplum deployments that are configured to automatically pull the :latest Docker tag. With our recent release of Medplum 4.0.0, these deployments may be caught in a failing deployment loop. This post explains why this is happening and how to resolve it.

The Issue​

Medplum 4.0.0 introduces significant improvements that require a data migration step. This migration must be completed while running version 3.3.0 before upgrading to 4.0.0 if your deployment contains data from before version 2.2.0 (released in November 2023).

If your deployment is:

  • Using the :latest Docker tag
  • Configured to automatically upgrade
  • Attempting to jump directly from a pre-3.3.0 version to 4.0.0

Then your deployment is likely failing and retrying in a loop.

How to Fix It​

If you're experiencing this issue, follow these steps to resolve it:

Important Caveat​

The data migration is only necessary for deployments that contain data from before version 2.2.0 (released in November 2023). If your deployment started on version 2.2.0 or later, you can skip the migration step using one of the methods described below.

  1. Stop the auto-update process temporarily:

    • Modify your deployment configuration to use a specific version tag (3.3.0) instead of :latest
    • This will break the failing deployment cycle

  2. Perform the required upgrade path:

    Pre-3.3.0 → 3.3.0 → Run Data Migration → 4.0.0

  3. Deploy version 3.3.0 explicitly:

    • Update your infrastructure-as-code (AWS CDK, Terraform, Helm charts, etc.) to use the specific 3.3.0 tag
    • Apply your updated infrastructure configuration to deploy version 3.3.0

  4. Run the data migration:

    • Log in to your Medplum admin interface
    • Navigate to the Admin panel
    • Click on the "Data Migration" button
    • Wait for the migration to complete successfully

  5. Update to 4.0.0:

    • Once migration is complete, you can safely update to 4.0.0
    • You may resume using :latest if desired, or pin to 4.0.0 for stability

Skipping the Migration (For Deployments Started on 2.2.0 or Later)​

If your deployment started on version 2.2.0 or later (November 2023), you can skip the migration step using one of these methods:

Option 1: Direct Database Update

-- Run this SQL query on your Postgres database
UPDATE "DatabaseMigration" SET "dataVersion"=1;

Option 2: API Command

In version 3.3.0, we also added an API endpoint to set the data version. You can use this endpoint to set the data version to 1.

# Get an auth token
export AUTH_TOKEN=$(npx medplum token)

# Use curl to set the data version
curl -X POST \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.medplum.com/admin/super/setdataversion \
  -d '{ "dataVersion": 1 }'

After using either option, you can proceed directly to upgrading to version 4.0.0.

Best Practices for Production Deployments​

This situation highlights some important deployment best practices:

  1. Avoid :latest in production: Always pin to specific version tags in production environments
  2. Read release notes: Always check release notes before upgrading, especially for major version changes
  3. Test upgrades in staging: Validate upgrade procedures in a non-production environment first
  4. Implement controlled rollouts: Consider using a controlled rollout strategy for updates

Looking Forward​

We understand this may have caused disruption for some users, and we're taking steps to improve our release process:

  • We're exploring ways to make the upgrade path more robust
  • We're enhancing our tooling to detect and prevent problematic upgrade paths
  • We're improving our documentation around version dependencies

Need Additional Help?​

If you continue to experience issues with your upgrade:

We're committed to helping every Medplum user successfully upgrade to version 4.0.0 and benefit from the latest improvements to our platform.