How to upgrade 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, see Getting Started, 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.