Breached password detection is a critical component of secure applications.    Read the white paper

FusionAuth logo
FusionAuth logo
  • Features
    FusionAuth Reactor

    FusionAuth Reactor is a powerful suite of features developed to extend FusionAuth's core functionality.

    • Flexible Architecture   Flexible Architecture
    • Auth the Way You Want It   Auth the Way You Want It
    • Security & Compliance   Security & Compliance
    • Ultimate Password Control   Ultimate Password Control
    • Customizable User Experience   Customizable User Experience
    • Advanced Registration Forms   Advanced Registration Forms
    • Built for Devs   Built for Devs
    • User Management & Reporting   User Management & Reporting
    • Scalability   Scalability
    • Single Sign-on   Single Sign-on
    • Breached Password Detection   Breached Password Detection
    • Connectors   Connectors
    • FusionAuth Reactor   FusionAuth Reactor
  • Pricing
    Cloud Pricing

    Let us host, monitor, manage, and maintain your deployments in your own private cloud.

    SEE PRICING cloud pricing   See FusionAuth Cloud Pricing
    Editions Pricing

    A powerful set of features with available support that extends FusionAuth's core functionality.

    SEE PRICING edition pricing   See FusionAuth Edition Pricing
    Editions + Cloud

    FusionAuth will handle everything so you can get back to building something awesome.

    GET STARTED Get started
  • Docs
  • Downloads
  • Resources
    FusionAuth Resources
    • Upgrade from SaaS
    • Upgrade from Open Source
    • Upgrade from Home Grown
    • Blog   Blog
    • Forum   Forum
    • Community & Support   Community & Support
    • Customer & Partners   Customers & Partners
    • Video & Podcasts   Videos & Podcasts
    • Getting Started   Getting Started
  • Expert Advice
    Expert Advice for Developers

    Learn everything you need to know about authentication, authorization, identity, and access management from our team of industry experts.

    • Authentication   Authentication
    • CIAM   CIAM
    • Identity Basics   Identity Basics
    • OAuth   OAuth
    • Security   Security
    • Tokens   Tokens
    • Dev Tools   Dev Tools
  • Account
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Reactor
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Authentication and Authorization
    • Integration Points
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cluster
    • Docker
    • Fast Path
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Securing
    • Upgrading
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consent
    • Emails
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Apple
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Twitter
      • OpenID Connect
      • SAML v2
      • External JWT
    • Integrations
    • JWT
    • Keys
    • Lambdas
    • Login
    • Passwordless
    • Registrations
    • Reports
    • System
    • Tenants
    • Themes
    • Two Factor
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Localization
    • Examples
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
  • Events & Webhooks
    • Overview
    • Events
    • Writing a Webhook
    • Securing Webhooks
  • Example Apps
    • Overview
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • Twitter Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Twitter
    • OpenID Connect
      • Overview
      • Azure AD
      • Github
      • Discord
    • SAML v2
      • Overview
      • ADFS
    • External JWT
      • Overview
      • Example
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Writing a Plugin
    • Password Encryptors
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Migration
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • Setup Wizard & First Login
    • Register/Login a User
    • Migrate Users
    • JSON Web Tokens
    • Authentication Tokens
    • Start and Stop FusionAuth
    • Switch Search Engines
    • User Account Lockout
    • Two Factor
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Encryptors
  • Release Notes
  • Troubleshooting

Upgrade FusionAuth

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.

Topics covered in this document:

  • ZIP Packages

  • Linux Packages

  • Database

  • Themes

If you used the FastPath or other installation methods 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, read on.

Readme

To upgrade to the latest version of FusionAuth using the FastPath installation go here.

To upgrade to the latest version of FusionAuth using Homebrew go here.

To upgrade to the latest version of FusionAuth using Docker go here.

If you want to use manual mode, download the latest version of FusionAuth and follow the instructions below. See Downloads.

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.

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

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!

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

Database

If you want FusionAuth to upgrade the database automatically, use the Silent Mode process, which will perform an automated upgrade.

If you want to use Maintenance Mode, ensure your runtime mode is set to development and silent mode is set to false.

If you want to upgrade the database manually, follow the instructions below.

For more on runtime modes, see the FusionAuth Installation Guide for reference.

For more information on the various configuration options, see the Configuration Reference.

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 finding the database zip on the Direct Downloads page.

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 FusionAuth migrations. Run them in order, starting with the first migration greater than the version you are coming from, and ending with the version that is less than or equal to the target upgrade version.

For example, if upgrading from version 1.19.1 to 1.22.0, run the following SQL migrations in this order:

  • 1.20.0.sql

  • 1.21.0.sql

  • 1.22.0.sql

fusionauth-database-schema/
|-- migrations/
    |--  [mysql | postgresql]/
      |-- 1.1.0.sql
      |-- 1.2.0.sql
      |-- 1.3.0.sql
      |-- 1.3.1.sql
      |-- 1.5.0.sql
      |-- 1.6.0.sql
      |-- 1.7.0.sql
      |-- 1.7.1.sql
      |-- 1.8.0-RC.1.sql
      |-- 1.8.1-RC.1.sql
      |-- 1.11.0.sql
      |-- 1.12.0.sql
      |-- 1.13.0.sql
      |-- 1.14.0.sql
      |-- 1.15.0.sql
      |-- 1.15.3.sql
      |-- 1.16.0-RC.1.sql
      |-- 1.16.0.sql
      |-- 1.17.0.sql
      |-- 1.17.3.sql
      |-- 1.18.0.sql
      |-- 1.18.2.sql
      |-- 1.19.0.sql
      |-- 1.20.0.sql
      |-- 1.21.0.sql
      |-- 1.22.0.sql
      |-- 1.23.0.sql

Themes

Templates

When new functionality is introduced to the hosted login pages, new theme templates are occasionally added. They are added to the default theme by the upgrade process, but if you’ve customized your theme to fit your brand, you’ll need to modify the theme to have the new template.

In the version release notes, any new templates are documented. This will tell you that you’ll want to take a closer look at the themes post upgrade.

As part of your upgrade testing, open the administrative user interface and navigate to Customizations > Themes.

If any themes are missing templates, they will show as "Upgrade Required". Port the new theme files over to your custom theme, modify them as needed, and save the theme.

Messages

When new functionality is introduced to the hosted login pages, new theme message keys are sometimes required. They are added to the default theme messages file by the upgrade process.

However, if you have customized your theme, the new keys are not added to that modified theme. The first time you try to modify your theme, you’ll receive an error message similar to the text below:

Missing required keys. See text area below for default English translations. To continue, please copy the values from below into the Messages text area.

FusionAuth warns you about missing required keys in order to avoid an inadvertent bad user experience. The default display for keys with no valid values in theme Messages is the key text, such as [ExternalAuthenticationException]LinkedInToken, which can be confusing for end users.

During an upgrade, you can find these keys by testing the upgrade on a development instance or comparing releases in the fusionauth-localization repo. You can safely add these new key values to your theme prior to an upgrade. Any unused messages in a theme’s messages file are silently ignored (unless malformed).

The extra lines won’t do any harm, and will ensure an excellent end user experience if they stumble on new functionality right after an upgrade.

Feedback

How helpful was this page?

See a problem?

File an issue in our docs repo

Quick Links

  • Download
  • Cloud Pricing
  • Editions Pricing
  • Contact Us
  • Jobs (come work with us)
  • My Account

Resources

  • Docs
  • Blog
  • Community & Support
  • Upgrade from SaaS
  • Upgrade from Homegrown
  • Upgrade from Open Source

Everything Else

  • Privacy Policy
  • Product Privacy Policy
  • License
  • License FAQ
  • Enterprise Sales FAQ
  • Security (contact, bug bounty, etc)
  • Technical Support

Connect with Us

logo
Subscribe for Updates
We only send dev friendly newsletters. No marketing fluff!
© 2021 FusionAuth