How to upgrade Vonk?

The process for upgrading Vonk depends on whether you have a vanilla Vonk FHIR 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 Vonk for details per each released version of Vonk.

Upgrading Vonk FHIR Server

Using the binary distribution

  1. Download the latest version of Vonk, 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 Vonk for any new settings that you may want to apply or change from their defaults.
  4. Check the Release notes Vonk 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 Vonk (Ctrl + C if running from the console).
  8. Switch to the new installation directory and start Vonk from there (> dotnet ./Vonk.Server.dll)
  9. Vonk 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 Vonk introduces a new version of the FHIR .NET API, Vonk 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 Vonk 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 Vonk.

If anything went wrong, go back:

  1. Stop the (new) running instance of Vonk.
  2. Restore both databases from your backup.
  3. Switch to the old installation directory and start the old version of Vonk from there (> dotnet .\Vonk.Server.dll)
  4. It should start as it did before you began the upgrade.
  5. Report the problem to the Vonk 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 Vonk installation. Anything specified in AdministrationImportOptions will be re-imported into the new database.

Using Docker

Revisit Using Vonk on Docker.

  1. Stop the running container for Vonk: > docker stop vonk.server.
  2. Pull the latest image for Vonk: > docker pull simplifier/vonk
  3. Check the Release notes Vonk 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 Vonk 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 Vonk on Docker for the various commands to run the Vonk container).
  7. Vonk 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 Vonk introduces a new version of the FHIR .NET API, Vonk 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 Vonk 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 Vonk.

If anything went wrong, go back:

  1. Stop the (new) running container of Vonk.
  2. Restore both databases from your backup.
  3. Specify your previous image of Vonk in the docker command or in the docker-compose file: simplifier\vonk:<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 Vonk helpdesk, see Contact us.

Upgrading Plugins

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

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 Vonk.* 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 Vonk version in the Release notes Vonk. Applying the changes should fix the errors.
  5. 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 :-)
  6. Build and publish your plugin.
  7. Put the resulting dll’s in the plugin directory of the new installation of Vonk.
  8. Re-include your plugin in the pipeline.
  9. (Re)start Vonk 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 Vonk 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 Vonk is using. Check the list of changes to see whether we upgraded.