Upgrading FOSSA

In this guide, we'll walk through how to upgrade your installed version of FOSSA.

This guide assumes you have set up Helm, installed FOSSA, and are familiar with updating Helm values.

Getting a new version of the chart

To get a new version of the FOSSA chart, you'll want to run:

$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "fossa" chart repository
Update Complete. ⎈Happy Helming!⎈

To see the latest chart versions you have locally, run:

$ helm search repo fossa/fossa-core
NAME               	CHART VERSION	APP VERSION          	DESCRIPTION
fossa/fossa-core   	2.6.10       	4.10.39              	Deploys the fossa-core monolith
# ...

If an update is available, you should see a new version of fossa/fossa-core available in this list.

Reading the changelog

Always read the changelog of Helm charts before running them.

FOSSA bundles its changelog inside the chart itself. It's always good practice to read the changelog of an upgrade before performing the upgrade.

Most importantly, our changelog will contain information about breaking changes. Occasional breaking upgrades may require you to take action outside of Helm, or change your Helm values.

To view the changelog, you'll need to download the Helm chart and examine its contents:

# Download and unpack the chart into a temporary folder
$ helm pull --untardir /tmp/fossa-helm --untar fossa/fossa-core

# Show the changelog
$ cat /tmp/fossa-helm/fossa-core/CHANGELOG.md

Read this document thoroughly before proceeding with the upgrade, and make sure to follow any instructions for breaking upgrades.

Most upgrades are not breaking, and require no user action beyond the usual upgrade commands. We will always clearly mark breaking upgrades in our changelog.

Running the upgrade

Once you have the new chart version, and you have read the changelog and performed any needed updates outside of Helm and to your Helm values, you're now ready to do the actual upgrade.

To upgrade FOSSA, you'll need the Helm release name that you installed FOSSA with.

Once you have that release name, run:

$ helm upgrade RELEASE_NAME fossa/fossa-core --values YOUR_VALUES_FILE.yaml --timeout 60m

⚠️ Use explicit --values files rather than --reuse-values. Helm has different and surprising value merging behavior when using --reuse-values. In particular, Helm will not merge new values from the updated chart when using --reuse-values.

Our charts are designed to protect you from this issue using a "minimum values version" field. If you see a Helm error that reads FOSSA has updated its default values. You're using X and the latest version is Y. Please upgrade without --reuse-values., then you may have accidentally used --reuse-values.

Helm will take a while to start up new services, and FOSSA may become briefly unavailable as services restart.

Once the upgrade completes, congratulations! You've upgraded your installation of FOSSA! 🎉