Migration Guide for `v0.14.x`

Use this guide only when you are on less than v0.14.0 and upgrading to v0.14.x.

Follow these steps when upgrading to 0.14.x. There is some downtime involved. During the downtime SDKs would receive a 503 Service Unavailable when sending sessions. Once the upgrade is complete, ingestion should resume normally. SDKs will retry sending unsent sessions automatically.

1. Shutdown all Measure servicesCopy Anchor Link

SSH into the VM where Measure is hosted.

cd ~/measure/self-host

sudo docker compose -f compose.yml -f compose.prod.yml --profile migrate down --remove-orphans

2. Perform the upgradeCopy Anchor Link

Visit Releases page to capture the latest tag matching the v[MAJOR].[MINOR].[PATCH] format. For example, v0.14.0.

cd ~/measure

git reset --hard # only applies if you have local modifications

git fetch --tags

# replace <git-tag> with the chosen tag. example: v0.14.0
git checkout <git-tag>

3. Start Measure servicesCopy Anchor Link

cd ~/measure/self-host

sudo ./install.sh

4. Run data back filling scriptCopy Anchor Link

Perform this step to complete the migration. Measure dashboard will not work properly until this script is run.

sudo ./migrations/v0.14.x-data-backfills.sh

If the script fails, it prints a command that resumes the backfill from the chunk that failed. Run that command.