Upgrading Firely Server

The process for upgrading Firely Server depends on whether you have a vanilla Firely Server, you added your own plugins or are running a Facade. This page describes the general process for each situation. Please refer to the Release notes Firely Server for details per each released version of Firely Server.

Upgrading Firely Server

Using the binary distribution

  1. Download the latest version of Firely Server and extract it to where you want it installed.

  2. Copy your appsettings.instance.json and logsettings.instance.json files from the current installation to the new installation.

  3. Check the Release notes Firely Server for any new settings that you may want to apply or change from their defaults.

  4. Check the Release notes Firely Server for any actions that you need to take specifically for this upgrade.

  5. Make sure the new installation can find the license file (see License, general advice is to put the license file outside of the installation directory).

  6. Create a backup of your current databases, both the main Resource database and the Administration database. See Repository to find the details on your configured database connection.

  7. Stop the running instance of Firely Server (Ctrl + C if running from the console).

  8. Switch to the new installation directory and start Firely Server from there (> dotnet ./Vonk.Server.dll)

  9. Firely Server will now do several upgrade tasks, during which any web request will be responded to with 423 - Locked:

    1. If needed, an update is applied to the database structure.

    2. If Firely Server introduces a new version of the FHIR .NET API, Firely Server will load a new set of Conformance Resources from the specification.zip into the Administration database, for both FHIR STU3 and FHIR R4. In a specific case you can prevent this step from happening.

  10. When Firely Server is done with the tasks above, it is again available to process requests.

  11. Check the log for warnings stating that you use obsolete settings. If so, adjust them and restart Firely Server.

If anything went wrong, go back:

  1. Stop the (new) running instance of Firely Server.

  2. Restore both databases from your backup.

  3. Switch to the old installation directory and start the old version of Firely Server from there (> dotnet .\Vonk.Server.dll)

  4. It should start as it did before you began the upgrade.

  5. Report the problem to the Firely Server helpdesk, see Contact us.

You may be able to avoid the import of specification.zip if:

  • The Administration database is in SQLite and

  • You have not made alterations to the Administration API through the Web API.

In this case you can simply replace the old database (usually with the filename vonkadmin.db) with the one from the new installation directory (in ./data/vonkadmin.db). Do so before you start the new Firely Server installation. Anything specified in AdministrationImportOptions will be re-imported into the new database.

Using Docker

Revisit Using Firely Server on Docker.

  1. Stop the running container for Firely Server: > docker stop vonk.server.

  2. Pull the latest image for Firely Server: > docker pull firely/server (versions 4.6 and older: > docker pull simplifier/vonk)

  3. Check the Release notes Firely Server for any new settings that you may want to apply or change from their defaults, and apply that to the environment setting in the docker-compose file.

  4. Check the Release notes Firely Server for any action that you need to take specifically for this upgrade.

  5. Create a backup of your current databases, both the main Resource database and the Administration database. See Repository and your docker-compose file to find the details on where your databases are.

  6. Start the new version (see Using Firely Server on Docker for the various commands to run the Firely Server container).

  7. Firely Server will now do several upgrade tasks, during which any web request will be responded to with 423 - Locked:

    1. If needed, an update is applied to the database structure.

    2. If Firely Server introduces a new version of the FHIR .NET API, Firely Server will load a new set of Conformance Resources from the specification.zip into the Administration database, for both FHIR STU3 and FHIR R4. In a specific case you can prevent this step from happening.

  8. When Firely Server is done with the tasks above, it is again available to process requests.

  9. Check the log for warnings stating that you use obsolete settings. If so, adjust them and restart Firely Server.

If anything went wrong, go back:

  1. Stop the (new) running container of Firely Server.

  2. Restore both databases from your backup.

  3. Specify your previous image of Firely Server in the docker command or in the docker-compose file: firely/server:<previous-version-tag>

  4. Start the container based on this previous image.

  5. It should start as it did before you began the upgrade.

  6. Report the problem to the Firely Server helpdesk, see Contact us.

Upgrading Plugins

Since a Plugin runs in the context of a Firely Server we advise you to start by upgrading your Firely Server, without loading your Plugin. Check the section on Configuring the Firely Server Pipeline to see how you can exclude your plugin from the pipeline.

Attention

We do not guarantee that a plugin built against version x.y.z of Firely Server can be run within a newer or older version as-is. Between minor versions recompilation is usually enough to update your plugin. Between major versions you should prepare for breaking changes in the public programming API. Sometimes we choose to apply such changes even on a minor version update, if we are fairly sure that you will not or only slightly be affected by it.

Upgrade the references in your plugin:

  1. Open the source code of your plugin, and open the project file (yourplugin.csproj).

  2. Change the references to the Firely Server.* packages to the version that you want to upgrade to.

  3. Build and check the errors.

  4. Check the list of breaking changes for the new Firely Server version in the Release notes Firely Server. Applying the changes should fix the errors.

  5. With some releases Firely Server is also upgraded to a newer version of the Firely .NET SDK. That is then mentioned in the release notes. If this is the case, also check the SDK release notes for breaking changes.

  6. Still errors? Maybe we have overlooked a change. Please report it to us, see Contact us. And if it is easy to fix - do so :-)

  7. Build and publish your plugin.

  8. Put the resulting dll’s in the plugin directory of the new installation of Firely Server.

  9. Re-include your plugin in the pipeline.

  10. (Re)start Firely Server and test the working of your plugin.

Upgrading Facades

A Facade implementation is technically also a plugin, but one that only adds repository access services. For this it makes no sense to try to run Firely Server without the Facade as is described for plugins. So start with upgrading the references right away.

Especially for Facades to relational databases: match the version of EntityFrameworkCore that the new version of Firely Server is using. Check the list of changes to see whether we upgraded.

Migrations

Sometimes, an upgrade of the database schema is needed in order to introduce performance improvements or enable new features. Depending on the database that is used, Firely Server provides different techniques to migrate the data. Most migrations can be performed automatically whereas in some cases, manual migrations are preferable.

One of these cases is a scenario in which Firely Server operates at scale, handling billions of resources. In such a scenario, manual migrations are preferable as they might take longer than expected and come with challenges. In this section, we will elaborate on some of these challenges and how to mitigate them.

MongoDB

For Firely Server instances running on MongoDB, we consider databases with more than 500GB as large. Migrations for these databases take a long time which is why we introduced external migration scripts with Firely Server 4.5.0. These external scripts are written in JavaScript and allow to exert more control at the cost of some convenience.

The migration scripts usually perform two operations in this order:
  1. Migrate the existing data using the updateMany() operator.

  2. Update the system information document to the next version.

While migrating large databases manually via SSH it is always a risk that the connection with the remote computer breaks and the SSH session terminates. Normally, this would also mean that all programs started within that SSH session will also be terminated including the migration. To prevent this from happening, we recommend using the screen tool to perform the migration. Using it allows programs to continue running even if the SSH connection breaks.

  1. Install the screen tool or check whether it is installed with screen --version

  2. Start a screen session: screen

  3. Execute the migration script in this screen session

  4. In case the SSH connection breaks, you can connect via SSH again and get access to the running migration process using the command screen -r

  5. Wait until the migration is done and restart Firely Server

In case the migration actually times out or is interrupted, the updateMany() operator will continue running in the background. The update of the schema version, however, will not succeed and needs to be performed manually. Follow these steps to do so:

  1. Connect to your MongoDB host.

  2. Open a MongoDB shell by executing mongo from the command line.

  3. Switch to the vonk database: use vonkdata

  4. Check whether the current migration is still running with: db.currentOp(). You will likely see multiple operations in this command’s output. Look for an operation that resembles the commands included in the try {} catch {} block in the migration’s JavaScript file. If any such operation is still listed, the migration is still running.

  5. Wait until the operation associated with the migration has finished.

  6. Afterwards, retrieve the system document id by executing:

    db.vonkentries.findOne(
       {
             "LatestMigration": { $exists: true }
       }
    )
    
  7. Note down the value of the _id field, for example ObjectId("61bc7dab260c691f4c0f78d4")

  8. Open the JavaScript migration script. Note down the value of the next FS and migration version. You will find these values as constants at the top of the migration script or in a coll.updateOne() command at the end of the script.

  9. Open a mongo shell on your host and exchange ObjectId, VonkVersion and LatestMigration to the previously noted values:

    db.vonkentries.updateOne(
       {
          _id: ObjectId("61bc7dab260c691f4c0f78d4")
       },
       {
          "$set": {
                VonkVersion: "4.9.0",
                LatestMigration: 22
          }
       }
    )
    
  10. Execute this command in your mongo shell

That’s it! The migration of the data is finished and the document containing the system information is updated accordingly. You should now be able to start the new version of Firely Server.

SQL Server

  1. Have a tool at hand that can execute T-SQL scripts. E.g. SQL Server Management Studio.

  2. Connect to the Firely Server database to be upgraded. We advice to try the script on an acceptance database first.

  3. Stop all instances of Firely Server that are connected to this database to avoid erroneous behaviour.

  4. Open the script matching your current migration. #. All migration scripts are in the /sqlserver subdirectory of the Firely Server distribution. #. The release notes mention the script name for a specific upgrade.

  5. Run the script. Some migrations may take quite long.

  6. Check the messages. A successful upgrade should end with Upgraded to Firely Server database schema <new database schema number> in <database name>.

  7. Now you can start Firely Server again.