Upgrade FusionAuth

1. Upgrading

In order to upgrade FusionAuth to a later version use the following guides. Below you will find steps to follow if you are using Debian or RPM packages on Linux, or the ZIP packages on macOS, Linux or Windows.

If you used the FastPath install scripts initially, you may prefer to use that same mode to download the latest version of FusionAuth. If you would like to continue by manually downloading the necessary packages, continue to read on.

Readme

To upgrade to the latest version of FusionAuth using the FastPath installation go here instead and pretend you never found this page.

If you want to continue in manual mode, download the latest version of FusionAuth and then continue. See Downloads.

2. ZIP Packages

FusionAuth is available in a zip package for macOS, Linux and Windows. If you are using the ZIP package, please use this guide to update an existing instance of FusionAuth.

2.1. macOS and Linux

In this example, we’ll assume you have previously installed FusionAuth in /usr/local/fusionauth and this directory will be referred to FUSIONAUTH_HOME. If you have used a different directory you can adjust the following example accordingly.

Example filesystem layout
/usr/local/fusionauth/bin
/usr/local/fusionauth/config
/usr/local/fusionauth/config/keystore
/usr/local/fusionauth/config/fusionauth.properties
/usr/local/fusionauth/data
/usr/local/fusionauth/fusionauth-app
/usr/local/fusionauth/fusionauth-search
/usr/local/fusionauth/java

The first step will be to shutdown the FusionAuth services.

Shutdown and Uninstall FusionAuth
# Stop Services
/usr/local/fusionauth/bin/shutdown.sh

# Delete or move existing installation
cd /usr/local/fusionauth
rm -rf ./fusionauth-app
rm -rf ./fusionauth-search
rm -rf ./bin

During an upgrade, most everything is saved in the database, so it is safe to delete these directories. To preserve your configuration and Elasticsearch index you want to be sure to preserve the following directories:

Preserve these directories
/usr/local/fusionauth/config
/usr/local/fusionauth/data
/usr/local/fusionauth/java
/usr/local/fusionauth/logs

Extract the new zips and place in FUSIONAUTH_HOME. In the following example, we are using the unzip command with the -n and the -q flags. The -q flag is optional, it causes the command to be run in quiet mode to reduce the amount of output to the console. The other flag -n is a no overwrite flag so that any configuration files are not overwritten.

Unzip the new packages with a no overwrite flag
unzip -nq new-fusionauth-app.zip
unzip -nq new-fusionauth-search.zip

Finally restart the FusionAuth services.

Startup FusionAuth
# Start Services
/usr/local/fusionauth/bin/startup.sh

2.2. Windows

In this example, we’ll assume you have previously installed FusionAuth in \fusionauth and this directory will be referred to FUSIONAUTH_HOME. If you have used a different directory you can adjust the following example accordingly.

Example filesystem layout
\fusionauth\bin
\fusionauth\config
\fusionauth\config\keystore
\fusionauth\config\fusionauth.properties
\fusionauth\data
\fusionauth\fusionauth-app
\fusionauth\fusionauth-search
\fusionauth\java

The first step will be to shutdown the FusionAuth services and delete the old installation.

Shutdown and Uninstall FusionAuth
# Stop Services
net stop FusionAuthApp
net stop FusionAuthSearch

# Uninstall Services
cd \fusionauth\fusionauth-app\apache-tomcat\bin
FusionAuthApp.exe /uninstall
cd \fusionauth\fusionauth-search\elasticsearch\bin
FusionAuthSearch.exe /uninstall

# Delete or move existing installation
cd \fusionauth
move fusionauth-app fusionauth-app-old
move fusionauth-search fusionauth-search-old

During an upgrade, most everything is saved in the database, so it is safe to delete these directories. To preserve your configuration and Elasticsearch index you want to be sure to preserve the following directories:

Preserve these directories
\fusionauth\config
\fusionauth\data
\fusionauth\java
\fusionauth\logs

Extract the new zips and place in FUSIONAUTH_HOME. You may do this using Windows File Explorer or other command line tools to unpack the zip archive. In this next step, ensure you delete or move the existing directories to ensure you do not unzip the new version on top of the existing version. If you do this, you will end up with duplicate libraries in the classpath that will lead to runtime errors.

After you have extracted the new packages, re-install the Windows services and start them.

Install and Start FusionAuth
# Install Windows Services
cd \fusionauth\fusionauth-app\apache-tomcat\bin
FusionAuthApp.exe /install
cd \fusionauth\fusionauth-search\elasticsearch\bin
FusionAuthSearch.exe /install

# Startup Services
net start FusionAuthSearch
net start FusionAuthApp

That is it, you’re done!

3. Linux Packages

Updating your application is easy if you installed using the RPM or Debian packages. All you need to do is to issue an update command to the dpkg or rpm program and specify the new package file. Here is an example:

Running the update script will shut down the FusionAuth service if they have not yet been stopped The service will need to be restarted after the update is finished.

Shutdown FusionAuth
sudo service fusionauth-app stop
sudo service fusionauth-search stop
Upgrade FusionAuth using Debian bundles
sudo dpkg -i fusionauth-search-<version>.deb
sudo dpkg -i fusionauth-app-<version>.deb
Upgrade FusionAuth using RPM bundles
sudo rpm -U fusionauth-search-<version>.rpm
sudo rpm -U fusionauth-app-<version>.rpm
Start FusionAuth
sudo service fusionauth-search start
sudo service fusionauth-app start

4. Database

In most cases, you will not need to upgrade you database manually using the information below. FusionAuth ships with a system called Maintenance Mode. When you restart FusionAuth after installing a new bundle using the steps above, FusionAuth will automatically upgrade your database.

You should always backup your database prior to using Maintenance Mode.

Depending on your current version and the new version you will be updating to you might need to execute one or more SQL scripts to update your database. These scripts are located in the migrations folder inside the Database Schema ZIP file. This file can be downloaded by logging into your account at fusionauth.io.

When upgrading your database from a previous version, be sure to only run the scripts located in the migrations folder, the base files mysql.sql and postgresql.sql should only be used during a clean installation when no database schema is present.

Inside of the database schema zip file, you will find the following FusionAuth migrations, run in this order, starting with the first migration that is greater than the version you are coming from, and ending with the version that is less than or equal to the target version.

fusionauth-database-schema
  |
  migrations
    |
    mysql | postgresql
      |
      |- 1.1.0.sql