FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Java Spring
      • Python Django
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • PagerDuty
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
      • Kickstart Custom Theme
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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 .deb or .rpm package on Linux, or a .zip package on macOS, Linux or Windows.

    Topics covered in this document:

    • ZIP Packages

    • Linux Packages

      • Troubleshooting Upgrade with RPMs

    • FastPath

    • Database

    • Themes

    • Downtime

    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\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

    Prior to version 1.37.0 the executable will be found in the apache-tomcat directory. For example,

    \fusionauth\fusionauth-app\apache-tomcat\bin\FusionAuthApp.exe

    Versions 1.37.0 through 1.39.0 do not support native Windows installation.

    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\bin
    FusionAuthApp.exe /install
    cd \fusionauth\fusionauth-search\elasticsearch\bin
    FusionAuthSearch.exe /install
    
    # Startup Services
    net start FusionAuthSearch
    net start FusionAuthApp

    Prior to version 1.37.0 you can find FusionAuthApp.exe at

    \fusionauth\fusionauth-app\apache-tomcat\bin\FusionAuthApp.exe

    Versions 1.37.0 through 1.39.0 do not support native Windows installation.

    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 systemctl start fusionauth-search
    sudo systemctl start fusionauth-app

    Troubleshooting Upgrade with RPMs

    Please review the procedure outlined below if attempting perform a clean install or upgrade using RPM’s and have experienced a failure that you have been unable to resolve. Please only consider these steps after other attempts have been unsuccessful.

    This will completely remove FusionAuth App and FusionAuth Search from your server. Proceed with caution.

    It is always recommended you back up the database before performing an upgrade or troubleshooting steps outlined here.

    The following steps will produce a clean installation preserving:

    • The FusionAuth config file found in /usr/local/fusionauth/config/fusionauth.properties

    • The Elasticsearch index found in /usr/local/fusionauth/data

    Below assumes both fusionauth-app and fusionauth-search will be un-installed and re-installed together. If you are not using fusionauth-search, you may ignore the steps related to this service.

    Manual Removal Steps

    1. Remove the RPM package for fusionauth-search and fusionauth-app

      • sudo rpm -e fusionauth-search

      • sudo rpm -e fusionauth-app

    2. Manually delete anything leftover from RPM

      • sudo rm -rf /usr/local/fusionauth/fusionauth-search/

      • sudo rm -rf /usr/local/fusionauth/fusionauth-app/

      • sudo rm -rf /usr/local/fusionauth/bin/

    3. After removal, the following directories will remain:

      • /usr/local/fusionauth/config/

      • /usr/local/fusionauth/data/ - In some cases this directory may not exist

      • /usr/local/fusionauth/java/ - While safe to delete, it is not necessary.

    4. Reinstall fusionauth-app and fusionauth-search.

      • Download the desired version of fusionauth-app and fusionauth-search

        • Direct download.

        • sudo rpm -i <file_to_be_installed>.rpm

    FastPath

    While FastPath is an option to perform an upgrade, the FastPath process limits the flexibility of installation in order to get up and running quickly. Therefore it is not recommended to use FastPath install scripts in a Production Environment.

    When in a production environment please utilize .deb or .rpm packages when on Linux. If you your production platform is macOS or Windows, please manually manage the upgrade using the .zip bundles.

    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
          |-- 1.25.0.sql
          |-- 1.26.0.sql
          |-- 1.27.0.sql
          |-- 1.28.0.sql
          |-- 1.28.1.sql
          |-- 1.29.1.sql
          |-- 1.30.0.sql
          |-- 1.30.1.sql
          |-- 1.30.2.sql
          |-- 1.32.0.sql
          |-- 1.33.0.sql
          |-- 1.35.0.sql
          |-- 1.36.0.sql
          |-- 1.37.0.sql
          |-- 1.40.1.sql
          |-- 1.41.0.sql
          |-- 1.43.0.sql
          |-- 1.44.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 and macros are documented. If there are changes, 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.

    Downtime

    System upgrades require downtime. This is typically on the order of seconds to minutes.

    In general, the process for upgrading from version 1.x-1 to version 1.x is:

    • Take down all nodes running 1.x-1.

    • Upgrade the database schema by running the migrations, bringing the database to version 1.x.

    • Upgrade the FusionAuth application and (if required) Elasticsearch packages, bringing your nodes to 1.x.

    • Start all FusionAuth nodes.

    The recommendation is that you automate the process and minimize downtime. For FusionAuth Cloud we use a configuration management tool and see downtime on the order of seconds for multi-node instances.

    You may also, if you are in an environment with a load balancer and creating nodes is easy, follow this process:

    • Stand up a node and install FusionAuth 1.x on it.

    • Replace a node running 1.x-1 out of the load balancer with the new node running 1.x.

    • Upgrade the database schema by running the migrations, bringing the database to version 1.x. If you are running in production and silent mode, FusionAuth will apply the changes, otherwise you must apply them out of band (by running the SQL scripts). Read more about silent mode.

    • Stand up another node and install FusionAuth 1.x on it.

    • Replace another node running 1.x-1 out of the load balancer with the new node running 1.x.

    • Repeat until you have updated all the nodes.

    There’s an open issue for n-1 version compatibility. Please vote that up if this is important to you.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Subscribe for developer updates