The v2.29.0 release of the SMS represents a significant technical milestone. The previous version of the SMS was based on RethinkDB, the developer of which went out of business in 2016. As of v2.29.0 the SMS has moved to MongoDB, a much more stable database.

However, the migration to a new database involves significant complexity and must be done carefully. Backups are required before proceeding and we recommend practicing this in a non-production environment before proceeding to a production migration.

<aside> ⚠️

Make sure to read through and follow these steps before updating the version of the SMS container. The new release is not backwards compatible, and care has to be taken to avoid downtime or data-loss.

At any time during this process, as long as the RethinkDB database is kept running, the upgrade can be rolled back by resetting the container entrypoint and downgrading the version.

</aside>

If you are using docker compose and one of our reference docker compose stacks, see the updated documentation at either Reference Compose Stack (Moodle) or Reference Compose Stack (Brightspace) for an idea of what your installation should look like at the end.

Migration steps are specific to your deployment but should follow the same pattern:

  1. Schedule a maintenance window. If everything goes well, this upgrade should only take around 30 minutes, but schedule in some extra time in case it has to be rolled back.
  2. Deploy a new MongoDB database. It should be accessible to both the worker and server SMS containers. If you are using the reference compose stack it’s just one container for both of these services.
  3. Add a new MONGO_URL environment variable that is accessible to the SMS installation. It should appear similar to the following format: MONGO_URL=mongodb://user:password@host:port/database-name?authSource=admin
  4. Change the entrypoint/command of the server and worker containers to a shell (eg. args: ['tail', '-f', '/dev/null']) so the SMS does not start automatically on restart.
  5. Update the SMS image version and deploy. Shell into the container.
  6. Generate a dump of your existing RethinkDB database. This can be done with the rethinkdb dump command (depending on your environment, you may need to do this somewhere else, and copy the files into the SMS container). The dump will be a .tar.gz file. Extract this somewhere accessible to the SMS container.
  7. Run npm run migratetomongo </path/to/dump>, where /path/to/dump is the extracted folder containing the .json and .info files with the dumped table data.
  8. Once it has completed, it will have successfully migrated all data to Mongo and re-generated Elasticsearch indices. Exit out of the shell.
  9. Reset the entrypoint to what it was initially and redeploy/restart the container
  10. Go to your SMS installation and verify the migration was successful. The upgrade should now be complete!

<aside> 💡

You may want to keep the database dump (or the Rethink instance itself) around for a bit, in case there were any errors with the migration, to avoid permanent data loss.

</aside>