diff --git a/site/docs/v1/tech/admin-guide/upgrade.adoc b/site/docs/v1/tech/admin-guide/upgrade.adoc index 5ae85c7f5f..f7eba88e86 100644 --- a/site/docs/v1/tech/admin-guide/upgrade.adoc +++ b/site/docs/v1/tech/admin-guide/upgrade.adoc @@ -4,44 +4,386 @@ title: Upgrade FusionAuth description: Learn how to upgrade FusionAuth using our bundles and migration scripts navcategory: admin --- +:page-liquid: -== 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. +If you're considering upgrading FusionAuth, this document will help you understand the upgrade process and how to plan for it. It also covers detailed instructions on how to upgrade FusionAuth on various platforms and distributions. Topics covered in this document: -* <> -* <> -** <> -* <> -* <> -* <> -* <> +* <> +** <> +** <> +** <> +* <> +** <> +** <> +** <> +** <> +** <> +** <> +** <> +* <> +** <> +** <> +** <> +** <> +* <> +* <> +** <> +** <> +** <> +** <> +** <> + +== When to Upgrade + +=== Reasons To Upgrade + +Upgrading to a newer version of FusionAuth can provide the following benefits: + +* Access to new features and improvements. +* Improved performance and stability. +* Critical security updates and patches. + +=== Reasons Not To Upgrade + +You might want to delay upgrading in the following situations: + +* Your current version meets all your requirements. +* You are in the middle of a project or have tight deadlines. +* You have concerns about compatibility with customizations or third-party integrations. + +=== Being Aware of Upgrade Options + +You can stay informed about new FusionAuth releases and updates by: + +* Signing up for link:/docs/v1/tech/admin-guide/releases#release-notifications[release notifications]. +* Monitoring the link:/docs/v1/tech/release-notes[release notes]. +* Joining the https://fusionauth.io/community[FusionAuth community] forum and/or Slack. +* Following FusionAuth on social media platforms, including https://twitter.com/FusionAuth[Twitter] and https://www.linkedin.com/company/fusionauth[LinkedIn]. +* Monitoring the https://github.com/FusionAuth/fusionauth-issues/issues[FusionAuth Issues GitHub repository]. + +== How to Think About Upgrades + +Before upgrading FusionAuth, there are a number of things to consider. Upgrading FusionAuth is similar to upgrading a library your application depends on. Go through each of the points below to see if any of them apply to your situation. + +=== Version Changes and Notes + +Read the link:/docs/v1/tech/release-notes[release notes]. Release notes help you understand how a version update affects your systems. + +The FusionAuth team strives to provide detailed information for every change in every version, including tying the change back to a GitHub issue. The release notes include details on new features, improvements, workarounds, bug fixes, and potential breaking changes. + +=== Testing -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. +Before starting the upgrade process on production, test the upgrade in a staging or development environment to identify potential issues. This is particularly important for upgrades involving multiple version jumps or a FusionAuth instance that has been heavily customized. + +=== Downtime and Database Migrations + +Plan for any downtime or maintenance windows required for the upgrade. If changes to the database schema are required, required data migrations could lead to downtime that affects end users. Such changes are always noted in the release notes. (Read the release notes carefully.) An upgrade without a schema change, on the other hand, may not require any downtime from an end-user perspective. + +FusionAuth can perform database migrations automatically and silently using a process called link:/docs/v1/tech/guides/silent-mode[Silent Mode]. + +If you want to run the database migrations interactively or with other tooling, you can run any needed scripts out of band (meaning directly on the database yourself). The general process would be to: + +- Remove all server nodes from a load balancer/proxy. +- Run the database migration scripts. +- Add all server nodes back to the load balancer/proxy. [NOTE] ==== -*Readme* +You should always back up your database before upgrading. Doing so gives you the ability to roll back. +==== + +The timing of the database upgrade is also important to note. When an upgraded node is started and connects to the database, it will lock the database immediately if configured for link:/docs/v1/tech/guides/silent-mode[Silent Mode] and the database requires upgrading. Silent Mode is an optional runtime mode that can automatically handle upgrades on startup. This means that the database will be unavailable to other nodes in the cluster until the upgrade is complete. Learn more about the different runtime modes and how they affect database upgrades in the <> section below. + +=== Connected Applications and Client Libraries + +A FusionAuth upgrade might mean that you need to upgrade your client libraries too. Check if this is needed before upgrading, as it will entail a more complex upgrade process and may require downtime from other components of a your system. + +In general, client libraries are forward-compatible, but any issues will be noted in the release notes. (Read the release notes carefully.) + +If you are using an OIDC compatible library in your application to log your users in, it is unlikely that this integration would require modification, but test it in a non-production environment to make sure. + +==== Client Library Versioning + +include::docs/v1/tech/client-libraries/_client-library-versioning.adoc[] + +=== Skipping Versions + +Sometimes, you will want to upgrade to a FusionAuth version that is multiple minor versions ahead of your current version. For example, you might want to upgrade from version 1.43.0 to 1.45.0. This is called a "version jump." FusionAuth can run all the necessary database migrations to get you to the latest version, or you can apply the database migrations yourself. + +To determine if you can perform a version jump, you should review the link:/docs/v1/tech/release-notes[release notes] carefully. If the releases focus on bug fixes and minor improvements, you can probably perform a version jump safely. Version jumping across patch versions, for example from 1.43.0 to 1.43.3, is usually safe. -To upgrade to the latest version of FusionAuth using the FastPath installation go link:/docs/v1/tech/installation-guide/fast-path[here]. +The alternative to a version jump is to migrate and test at each version of FusionAuth. This is a good option because if there are any issues, you'll be able to know precisely which version of FusionAuth is problematic. It's a great option if you have automated tests that can exercise FusionAuth integrations. -To upgrade to the latest version of FusionAuth using Homebrew go link:/docs/v1/tech/installation-guide/homebrew[here]. +Whichever approach you take, you should always test the upgrade in a staging environment to identify potential issues. This is particularly important on more complex upgrades where you are moving between distant minor versions (from 1.22.0 to 1.43.0, for example) or if you have made customizations to FusionAuth. We recommend that the staging environment be as close as possible to your production environment. This includes using the same data, or at least the same data volume, as production. This enables you to test both functionality changes and data update performance times before committing to the upgrade on production. -To upgrade to the latest version of FusionAuth using Docker go link:/docs/v1/tech/installation-guide/docker[here]. +=== Updating Configuration -If you want to use manual mode, download the latest version of FusionAuth and follow the instructions below. See https://fusionauth.io/download[Downloads]. +Review the release notes to verify if the new version has any new configuration options with defaults that affect your installation. + +There are a number of options for managing the configuration of your FusionAuth instance over time and promoting changes from one environment to another. This includes changes from one version to another. + +Configuration management options include: + +- Scripting changes using a client library. +- Terraform. +- Pulumi. +- Manual configuration via the UI. + +You can read more in link:/docs/v1/tech/admin-guide/configuration-management[the Configuration Management guide]. + +// this has a hardcoded header +include::docs/v1/tech/installation-guide/_theme-upgrade.adoc[] + +== Upgrade Options + +[WARNING] +==== +Maintenance Mode should never be used in production. You don't want your end users to be prompted to update a database, which is what Maintenance Mode does. + +You should always back up your database before upgrading regardless of the upgrade method you choose. +==== + +For each of the options below, FusionAuth is running any database migrations. However, you can also stop all nodes and run the database migration SQL statements yourself, rather than relying on FusionAuth to run them. See <> for more. + +=== Easiest Route + +The easiest upgrade route is to simply stop all your services, upgrade each FusionAuth node, and then bring it all back online. In this case, FusionAuth will be performing the database upgrade, if needed, when the first node connects to the database. + +This is a good option for development instances or non-production systems such as QA. + +This is also a good option for systems that can tolerate longer periods of downtime. For instance, if you know you have near-zero user activity at midnight, you can upgrade then. If you have scheduled downtime for other components of your system, that is a good time to upgrade FusionAuth in this manner. + +If minimizing downtime is a goal, then rolling upgrades or a blue-green deployment might be more suitable. + +=== Rolling Upgrade + +You can perform a rolling upgrade if you have multiple FusionAuth nodes running behind a load balancer. The nodes are upgraded one at a time, and the load balancer is configured to direct traffic to the upgraded nodes as they become available for use. This allows you to upgrade FusionAuth with minimal downtime. + +[NOTE] ==== +This upgrade method requires a load balancer and multiple FusionAuth nodes. +==== + +Because individual nodes are taken offline during the rolling upgrade, the capacity of your installation is reduced during the upgrade. + +You can choose to run in-place upgrades on each node or to replace each node with a new node running the latest version of FusionAuth. In-place upgrades are simpler and faster because you don't have to spin up a new server, but if something goes wrong, rolling back the upgrade is more complex. Replacing nodes may be slower, but if something goes wrong, you can revert to the previous version of FusionAuth by pointing the load balancer to the old nodes. + +An in-place rolling upgrade procedure for a three node cluster might look like this: + +1. Stop the first node and remove it from the load balancer. +2. Upgrade FusionAuth on the first node. +3. Start FusionAuth on the upgraded node. +4. The upgraded node will perform required database migrations.* +5. Add the first node back to the load balancer. +6. Remove the second and third nodes from the load balancer +7. Stop the second and third nodes. +8. Upgrade the second and third nodes. +9. Start the second and third nodes. +10. Add the second and third nodes back to the load balancer. + +* The FusionAuth instance on the upgraded node will lock the database and own it while the database upgrade is completed. Note that there will be a schema mismatch between the first node and the other nodes, so the other nodes may give errors while the first node is being upgraded. The nature of these errors depends on the code paths being updated as well as how users interact with the system. *Errors should be minimal for core login functionality.* + +Downtime for this upgrade method is limited to the time it takes the first node to run the database migration. There will be limited capacity while the second and third nodes are upgrading, but the system will be available for use for most of the upgrade process. + +++++ +{% mermaid %} +graph TB + A(Users) --> B(Load Balancer) + B --> |Switch traffic when ready
Upgrade one node at a time| C(Node 1) + B --> D(Node 2) + B --> E(Node 3) + style C fill:#C0F0C0 +{% endmermaid %} +++++ + +=== Blue-Green Deployment + +A blue-green deployment is a technique that reduces downtime and risk by running two identical environments in parallel. A load balancer is used to direct traffic to one of the environments. Using a blue-green deployment isolates the upgrade process from the existing production servers, reducing the impact and risk compared to a rolling upgrade. + +[NOTE] +==== +This upgrade method requires a load balancer and multiple FusionAuth nodes. +==== + +To perform a blue-green deployment with a three node cluster, follow these steps. + +1. Create three new nodes with the new version of FusionAuth. +2. Start FusionAuth on one of the new nodes. +3. The new node will perform required database migrations.* +4. Add the new nodes to the load balancer. +5. Remove the old nodes from the load balancer. + +* The FusionAuth instance on the upgraded node will lock the database and own it while the database upgrade is completed. Note that there will be a schema mismatch between the first node and the other nodes, so the other nodes may give errors while the first node is being upgraded. The nature of these errors depends on the code paths being updated as well as how users interact with the system. *Errors should be minimal for core login functionality.* + +Downtime for this upgrade method is limited to the time it takes the first node to run the database migration, and the system will be back online at full capacity with the upgraded version of FusionAuth on the new nodes immediately following the migration. + + +++++ +{% mermaid %} +graph TB + A(Users) --> B(Load Balancer) + subgraph green [Green Deployment - new version] + C(Node 1) + D(Node 2) + E(Node 3) + style C fill:#C0F0C0 + style D fill:#C0F0C0 + style E fill:#C0F0C0 + end + subgraph blue [Blue Deployment - old version] + F(Node 1) + G(Node 2) + H(Node 3) + style F fill:#add8e6 + style G fill:#add8e6 + style H fill:#add8e6 + end + B --> |Switch traffic when ready|green + B --> blue +{% endmermaid %} +++++ + +=== Out-of-Band Database Upgrades + +FusionAuth can handle database migrations automatically using link:/docs/v1/tech/guides/silent-mode[Silent Mode]. FusionAuth can also handle updates interactively on development environments using link:/docs/v1/tech/installation-guide/fusionauth-app#maintenance-mode[Maintenance Mode]. + +In production you may want to perform the database migration yourself rather than allow FusionAuth to do so. This is also known as an out-of-band upgrade. This is useful if you want to perform the database migration in a way that minimizes downtime or as part of a larger automated or coordinated upgrade process. Performing the database migration involves running SQL scripts to update the database schema. + +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 in the Database Schema ZIP file, which you can download from the link:/direct-download[Direct Downloads] page. + +[WARNING] +==== +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. +==== + +Find the FusionAuth migrations in the Database Schema ZIP file. Run them in order, starting with the first migration greater than your current FusionAuth version, 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` + +[source] +---- +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 + |-- 1.45.2.sql + |-- 1.46.0.sql + |-- 1.47.0.sql +---- + +== Rolling Back an Upgrade + +If your upgrade is unsuccessful or causes unexpected issues, you may need to roll back your FusionAuth instance to a previous version. + +Here are the steps for initiating a rollback: + +1. Stop your FusionAuth instances. +2. Initiate the process to restore from the database backup taken prior to starting the upgrade. +3. Redeploy FusionAuth using your previous version. How you do this will depend on your deployment method. + +If you are running a FusionAuth Cloud deployment, you can find instructions for rolling back an upgrade here: link:/docs/v1/tech/installation-guide/cloud#rolling-back-from-a-problematic-upgrade[Rolling Back From a Problematic Upgrade]. + +It's important to consider the timing implications of a rollback or any disaster recovery process. RTO, or Recovery Time Objective, is the targeted period time within which a service should be restored after an outage to avoid unacceptable consequences. Simply put, it is how long you can afford to be without the service or system before it severely impacts your business. It represents the goal for the time taken to recover from failure. + +RPO, or Recovery Point Objective, on the other hand, refers to the maximum tolerable amount of data loss measured in time. Determine RPO by looking at the time of the last backup you need to restore from and the restore time. + +In the context of a FusionAuth upgrade rollback, the RPO would be the time since the last backup before the upgrade, and the RTO would be the time it takes to stand up the older version of the system and restore the database. + +The RPO effectively measures the maximum tolerable data loss in the event of a rollback, and the RTO measures the time it takes to recover from the failure. + + +== Upgrade FAQs + +include::docs/v1/tech/installation-guide/_modes.adoc[] + +**Q:** How many versions can I skip? + +**A:** We recommended migrating from one minor version to the next. Read the release notes carefully and test your upgrade in a non-production environment. + +**Q:** How often should I upgrade? + +**A:** We recommend staying within the last three minor versions, but we will not force an upgrade. In addition, we typically don't backport bug fixes. If you run into an issue with a bug, you'll need to upgrade to get the fix. We recommend you set up a regular cadence of reviewing and upgrading FusionAuth that fits your business needs, the same as you would with a framework or library your application depends on. + + +**Q:** How can I find out about new releases? + +**A:** We publish release notes for every release. You can find them here: link:/docs/v1/tech/release-notes[Release Notes]. There are a variety of ways to be link:/docs/v1/tech/admin-guide#release-notifications/releases[notified of releases], including an email list and RSS feed. +**Q:** Does FusionAuth support zero-downtime upgrades? + +**A:** At this time, FusionAuth does not support zero-downtime upgrades when there is a database change. While there are a variety of options that can minimize downtime, upgrades will cause downtime whenever a schema change is required. Please https://github.com/FusionAuth/fusionauth-issues/issues/1240[review and upvote this issue] if zero-downtime upgrades are important to you. -== ZIP Packages +== Detailed Upgrade Instructions -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. +This section will guide you with detailed technical instructions on how to upgrade FusionAuth nodes on different platforms. -=== macOS and Linux +=== Cloud -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. +To upgrade your FusionAuth Cloud instance, see the link:/docs/v1/tech/installation-guide/cloud#upgrading-a-deployment[Cloud Installation Guide]. + +=== Docker + +include::docs/v1/tech/shared/_upgrade-using-docker.adoc[] + +=== Homebrew + +include::docs/v1/tech/shared/_upgrade-using-brew.adoc[] + + +=== 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. Find the ZIP packages at the FusionAuth https://fusionauth.io/download[Downloads] page. + +==== 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 as `FUSIONAUTH_HOME`. If you have used a different directory you can adjust the following example accordingly. [source,title=Example filesystem layout] ---- @@ -55,11 +397,11 @@ In this example, we'll assume you have previously installed FusionAuth in `/usr/ /usr/local/fusionauth/java ---- -The first step will be to shutdown the FusionAuth services. +The first step will be to shut down the FusionAuth services. -[source,title=Shutdown and Uninstall FusionAuth] +[source,title=Shut down and uninstall FusionAuth] ---- -# Stop Services +# Stop services /usr/local/fusionauth/bin/shutdown.sh # Delete or move existing installation @@ -69,7 +411,7 @@ 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: +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: [source,title=Preserve these directories] ---- @@ -79,25 +421,25 @@ During an upgrade, most everything is saved in the database, so it is safe to de /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. +Extract the new ZIP files and place them in `FUSIONAUTH_HOME`. In the following example, we use the `unzip` command with the `-n` and `-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. -[source,title=Unzip the new packages with a no overwrite flag] +[source,title=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. +Finally, restart the FusionAuth services. -[source,title=Startup FusionAuth] +[source,title=Start up FusionAuth] ---- # Start Services /usr/local/fusionauth/bin/startup.sh ---- -=== Windows +==== 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. +In this example, we'll assume you have previously installed FusionAuth in `\fusionauth` and this directory will be referred to as `FUSIONAUTH_HOME`. If you have used a different directory, you can adjust the following example accordingly. [source,title=Example filesystem layout] ---- @@ -111,9 +453,9 @@ In this example, we'll assume you have previously installed FusionAuth in `\fusi \fusionauth\java ---- -The first step will be to shutdown the FusionAuth services and delete the old installation. +The first step will be to shut down the FusionAuth services and delete the old installation. -[source,title=Shutdown and Uninstall FusionAuth] +[source,title=Shut down and uninstall FusionAuth] ---- # Stop Services net stop FusionAuthApp @@ -133,14 +475,14 @@ move fusionauth-search fusionauth-search-old [NOTE] ==== -Prior to version `1.37.0` the executable will be found in the `apache-tomcat` directory. For example, +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: +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: [source,title=Preserve these directories] ---- @@ -150,11 +492,11 @@ During an upgrade, most everything is saved in the database, so it is safe to de \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. +Extract the new ZIP files and place them in `FUSIONAUTH_HOME`. You may do this using Windows File Explorer or other command line tools to unpack the ZIP archive. Ensure you delete or move the existing directories to prevent unzipping the new version on top of the existing version. If the new version is unzipped on top of the existing version, 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. +After you have extracted the new packages, reinstall the Windows services and start them. -[source,title=Install and Start FusionAuth] +[source,title=Install and start FusionAuth] ---- # Install Windows Services cd \fusionauth\fusionauth-app\bin @@ -169,25 +511,25 @@ net start FusionAuthApp [NOTE] ==== -Prior to version 1.37.0 you can find `FusionAuthApp.exe` at +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: +=== 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: [NOTE] ==== -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. +Running the update script will shut down the FusionAuth service if it has not yet been stopped. The service will need to be restarted after the update is finished. ==== -[source,title=Shutdown FusionAuth] +[source,title=Shut down FusionAuth] ---- sudo service fusionauth-app stop sudo service fusionauth-search stop @@ -211,112 +553,13 @@ sudo systemctl start fusionauth-search sudo systemctl start fusionauth-app ---- -=== Troubleshooting Upgrade with RPMs +==== Troubleshooting Upgrade with RPMs include::docs/v1/tech/shared/_troubleshooting-uninstall-upgrade-reinstall-rpm.adoc[] === 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 - -[NOTE] -==== -If you want FusionAuth to upgrade the database automatically, use the link:/docs/v1/tech/guides/silent-mode[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 link:/docs/v1/tech/installation-guide/fusionauth-app#runtime-modes[FusionAuth Installation Guide] for reference. - -For more information on the various configuration options, see the link:/docs/v1/tech/reference/configuration[Configuration Reference]. -==== - -[NOTE] -==== -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 https://fusionauth.io/direct-download[Direct Downloads] page. - -[WARNING] -==== -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` - -[source] ----- -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 - |-- 1.45.2.sql - |-- 1.46.0.sql - |-- 1.47.0.sql ----- - -== Themes - -include::docs/v1/tech/installation-guide/_theme-upgrade.adoc[] +While FastPath is an option to perform an upgrade, the FastPath process limits the flexibility of the installation in order to get it up and running quickly. We therefore don't recommend you use FastPath install scripts in a production environment. -== Downtime +We recommend using `.deb` or `.rpm` packages on Linux production environments. If your production platform is macOS or Windows, please manually manage the upgrade using the `.zip` bundles. -include::docs/v1/tech/installation-guide/_downtime-upgrade-limitation.adoc[] diff --git a/site/docs/v1/tech/client-libraries/_client-library-versioning.adoc b/site/docs/v1/tech/client-libraries/_client-library-versioning.adoc new file mode 100644 index 0000000000..913c22b179 --- /dev/null +++ b/site/docs/v1/tech/client-libraries/_client-library-versioning.adoc @@ -0,0 +1,31 @@ +Client library versions track the API. The API will only change with a major or minor version release, not with a patch release. + +You should use the version of a client library that corresponds to your version of FusionAuth. If that is not available, use the latest release of the client library for the minor version. + +.Examples of Client Library Versions To Use +[cols="1,1,3"] +|=== +| FusionAuth Version | Client Library Version | Notes + +| `1.41.0` +| `1.41.0` +| Same version + +| `1.41.1` +| `1.41.0` +| Same minor version + +| `1.29.4` +| `1.29.1` +| Latest release in the minor version + +| `1.29.1` +| `1.29.1` +| Same version + +| `1.29.0` +| `1.29.0` +| Same version + +|=== + diff --git a/site/docs/v1/tech/client-libraries/index.adoc b/site/docs/v1/tech/client-libraries/index.adoc index 9bc0feabf1..647291327d 100644 --- a/site/docs/v1/tech/client-libraries/index.adoc +++ b/site/docs/v1/tech/client-libraries/index.adoc @@ -71,34 +71,4 @@ include::docs/v1/tech/client-libraries/_how-to-use-client-libraries.adoc[] == Versioning -Client library versions track the API. The API will only change with a major or minor version release, not with a patch release. - -You should use the version of a client library that corresponds to your version of FusionAuth. If that is not available, use the latest release of the client library for the minor version. - -.Examples of Client Library Versions To Use -[cols="1,1,3"] -|=== -| FusionAuth Version | Client Library Version | Notes - -| `1.41.0` -| `1.41.0` -| Same version - -| `1.41.1` -| `1.41.0` -| Same minor version - -| `1.29.4` -| `1.29.1` -| Latest release in the minor version - -| `1.29.1` -| `1.29.1` -| Same version - -| `1.29.0` -| `1.29.0` -| Same version - -|=== - +include::docs/v1/tech/client-libraries/_client-library-versioning.adoc[] diff --git a/site/docs/v1/tech/installation-guide/_modes.adoc b/site/docs/v1/tech/installation-guide/_modes.adoc new file mode 100644 index 0000000000..4413738192 --- /dev/null +++ b/site/docs/v1/tech/installation-guide/_modes.adoc @@ -0,0 +1,8 @@ +**Q:** What is runtime mode and how does it affect upgrades? + +**A:** FusionAuth runtime mode can be either `production` or `development`. When in the `development` runtime mode, Maintenance Mode will interactively assist you to configure the database and connect to Elasticsearch, if configured. Once you move FusionAuth into production, it is recommended that you modify the runtime mode to `production`. When in `production` runtime mode, Maintenance Mode will no longer be available to you, which means you can be certain that your end users will not find themselves on the database upgrade panel during an upgrade. When in `production` mode, you will either need to leverage Silent Mode to automatically apply database migrations or you will need to apply the database migrations yourself (either by hand or via a script of some sort). For more on runtime modes, see the link:/docs/v1/tech/installation-guide/fusionauth-app#runtime-modes[FusionAuth Installation Guide]. + +**Q:** What is Maintenance Mode? + +**A:** Maintenance Mode is a special admin interface for FusionAuth installations in development environments. Maintenance Mode helps you to interactively upgrade FusionAuth or set up database connections. You can switch to Maintenance Mode by switching to the `development` runtime mode and setting Silent Mode to false. Note that Maintenance Mode should never be used in production. + +**Q:** What is Silent Mode? + +**A:** link:/docs/v1/tech/guides/silent-mode[Silent Mode] is a feature of FusionAuth that automatically applies database migrations. This is useful for automated deployments. Silent Mode can be enabled in the `development` runtime mode and, as of version `1.19.0`, in the `production` runtime mode too. Silent Mode will attempt to perform database migrations on startup. If the database migrations fail, FusionAuth will display an error message on the login page. You should always test your database migrations in a non-production or staging environment before deploying to production. \ No newline at end of file diff --git a/site/docs/v1/tech/installation-guide/_theme-upgrade.adoc b/site/docs/v1/tech/installation-guide/_theme-upgrade.adoc index 0271343ce2..08238e8c39 100644 --- a/site/docs/v1/tech/installation-guide/_theme-upgrade.adoc +++ b/site/docs/v1/tech/installation-guide/_theme-upgrade.adoc @@ -2,12 +2,48 @@ When new functionality is introduced to link:/docs/v1/tech/core-concepts/integration-points#hosted-login-pages[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. +New templates and macros are documented in the release notes. If there are additions to a theme, you'll want to take a closer look at the themes after the upgrade. As part of your upgrade testing, open the administrative user interface and navigate to [breadcrumb]#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. +In some cases, existing templates are modified. If you have customized your theme, you'll need to compare the new template to your existing version's base theme and port over any changes to your customized theme. The easiest way to do this is to use a diff tool to compare the two sets of files. Here is a suggested process to follow before you upgrade: + +1. Download the default theme from your existing version of FusionAuth. +2. Download the default theme from the new version of FusionAuth. +3. Use a diff tool to compare the two sets of files. +4. Apply any differences to your customized theme. + +You can use the https://github.com/FusionAuth/fusionauth-theme-helper[Theme Helper] to help with this process. + +==== Using the Theme Helper to Upgrade Themes + +Clone the https://github.com/FusionAuth/fusionauth-theme-helper[Theme Helper repo] and follow the install instructions in the `README.md` file. + +Download the base themes from your existing version of FusionAuth and the new version of FusionAuth to compare. + +To get the existing version's theme files, create a `.env` file from the `.env.sample` file. Use the FusionAuth administrative user interface to create an link:/docs/v1/tech/apis/authentication#managing-api-keys[API key] with read permissions for Themes. Add the API key to the `.env` file. The link:/docs/v1/tech/reference/limitations#default-configuration[default theme] uses the ID `75a068fd-e94b-451a-9aeb-3ddb9a3b5987` across all instances. Use this value to update the `THEME_ID` key in the `.env` file. + +In the `.env` file, set the `FUSIONAUTH_URL` to the URL of your existing FusionAuth instance. Finally, update the `TMP_DIR` to a directory on your local machine where you want the existing theme files to be downloaded, such as `current-theme`. + +Now you can run the `download.sh` script to download the existing theme files to the `TMP_DIR` directory. + +Once the download is complete, you'll need to get the base theme files from the new version of FusionAuth. The easiest way to do this is to install the new version of FusionAuth on your local machine or a VM using Docker. Instructions for installing FusionAuth using Docker can be found in the link:/docs/v1/tech/installation-guide/docker#docker-compose[FusionAuth Docker Installation Guide]. + +Once you've got the new version of FusionAuth running, you can update the Theme Helper `.env` file in the Theme Helper repo to point to the new version of FusionAuth. If running locally, update the `FUSIONAUTH_URL` to `\http://localhost:9011`. + +Log in to the new version of FusionAuth to create an API key and use the same link:/docs/v1/tech/reference/limitations#default-configuration[default theme] ID `75a068fd-e94b-451a-9aeb-3ddb9a3b5987` for the `THEME_ID` variable as you did for the existing version. Finally, update the `TMP_DIR` to a directory on your local machine where you want the new theme files to be downloaded, such as `new-theme`. Make sure it is a different directory than the one you used for the existing theme files. + +Now you can run the `download.sh` script again to download the new theme files to the `TMP_DIR` directory. + +Once you have both sets of theme files downloaded, you can run the `diff-themes.sh` script to compare the two sets of files. The script takes two arguments: the path to the existing theme files and the path to the new theme files. For example: + +```sh +./diff-themes.sh current-theme new-theme +``` +The script will output a list of files with differences between the two themes along with the detailed diff for each file. You can use this output to update your customized theme files or use the file list as a guide along with an external diff tool. + === Messages When new functionality is introduced to link:/docs/v1/tech/core-concepts/integration-points#hosted-login-pages[the hosted login pages], new theme message keys are sometimes required. They are added to the default theme `messages` file by the upgrade process. @@ -20,7 +56,7 @@ Missing required keys. See text area below for default English translations. To 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 [field]#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 link:https://github.com/FusionAuth/fusionauth-localization/[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). +During an upgrade, you can find these keys by testing the upgrade on a development instance or comparing releases in the link:https://github.com/FusionAuth/fusionauth-localization/[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. +The extra lines won't do any harm and will ensure an excellent end-user experience if a user stumbles on new functionality right after an upgrade. diff --git a/site/docs/v1/tech/installation-guide/docker.adoc b/site/docs/v1/tech/installation-guide/docker.adoc index 7dc33a331b..d0bc76078e 100644 --- a/site/docs/v1/tech/installation-guide/docker.adoc +++ b/site/docs/v1/tech/installation-guide/docker.adoc @@ -199,12 +199,7 @@ image:installation-guides/mailcatcher-client.png[Mailcatcher Client View,width=1 == Upgrading -To upgrade FusionAuth when running with `docker-compose`: - -. Stop the instance: `docker compose down`. -. Modify the `docker-compose.yml` file to point to the version of FusionAuth you want. You can see https://hub.docker.com/r/fusionauth/fusionauth-app[available tags]. -. Start it up: `docker compose up`. -. Login to the administrative UI. +include::docs/v1/tech/shared/_upgrade-using-docker.adoc[] === Migrations diff --git a/site/docs/v1/tech/installation-guide/fusionauth-app.adoc b/site/docs/v1/tech/installation-guide/fusionauth-app.adoc index 3d490dcee2..48998a3fac 100644 --- a/site/docs/v1/tech/installation-guide/fusionauth-app.adoc +++ b/site/docs/v1/tech/installation-guide/fusionauth-app.adoc @@ -17,6 +17,7 @@ bundle provides access to the API and the web based user interface. - <> - <> - <> +- <> == Download the Package @@ -127,6 +128,7 @@ sudo systemctl start fusionauth-app net start FusionAuthApp ---- + == Runtime Modes The runtime mode may be configured to trigger or suppress environment specific runtime behavior. @@ -339,3 +341,7 @@ the instructions in the <> section above. include::docs/v1/tech/installation-guide/_troubleshooting-runtime-modes-at-startup.adoc[] +== FAQs + +include::docs/v1/tech/installation-guide/_modes.adoc[] + diff --git a/site/docs/v1/tech/installation-guide/homebrew.adoc b/site/docs/v1/tech/installation-guide/homebrew.adoc index 658ec2a964..77e6cb0ca8 100644 --- a/site/docs/v1/tech/installation-guide/homebrew.adoc +++ b/site/docs/v1/tech/installation-guide/homebrew.adoc @@ -38,28 +38,4 @@ The shared configuration file will be located here: `/usr/local/etc/fusionauth/f == Homebrew Upgrade -If you initially installed FusionAuth using Homebrew, you can also use Homebrew to upgrade to the latest version of FusionAuth. - -To upgrade FusionAuth using brew, first stop services. - -``` -brew services stop fusionauth-search -brew services stop fusionauth-app -``` - -Next, upgrade services. - -:code_id: homebrew-upgrade-script -[source] ----- -brew upgrade fusionauth-app fusionauth-search ----- -:code_id!: - -Start the services. - -[source] ----- -brew services start fusionauth-search -brew services start fusionauth-app ----- +include::docs/v1/tech/shared/_upgrade-using-brew.adoc[] diff --git a/site/docs/v1/tech/shared/_troubleshooting-uninstall-upgrade-reinstall-rpm.adoc b/site/docs/v1/tech/shared/_troubleshooting-uninstall-upgrade-reinstall-rpm.adoc index 96aded3dee..bad56e86ba 100644 --- a/site/docs/v1/tech/shared/_troubleshooting-uninstall-upgrade-reinstall-rpm.adoc +++ b/site/docs/v1/tech/shared/_troubleshooting-uninstall-upgrade-reinstall-rpm.adoc @@ -1,4 +1,4 @@ -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. +Please review the procedure outlined below if attempting to 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. [WARNING] ==== @@ -12,7 +12,7 @@ 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. +Below assumes both `fusionauth-app` and `fusionauth-search` will be uninstalled and reinstalled together. If you are not using `fusionauth-search`, you may ignore the steps related to this service. === Manual Removal Steps diff --git a/site/docs/v1/tech/shared/_upgrade-using-brew.adoc b/site/docs/v1/tech/shared/_upgrade-using-brew.adoc new file mode 100644 index 0000000000..8e1cc744f4 --- /dev/null +++ b/site/docs/v1/tech/shared/_upgrade-using-brew.adoc @@ -0,0 +1,25 @@ +If you initially installed FusionAuth using Homebrew, you can also use Homebrew to upgrade to the latest version of FusionAuth. + +To upgrade FusionAuth using brew, first stop services. + +``` +brew services stop fusionauth-search +brew services stop fusionauth-app +``` + +Next, upgrade services. + +:code_id: homebrew-upgrade-script +[source] +---- +brew upgrade fusionauth-app fusionauth-search +---- +:code_id!: + +Start the services. + +[source] +---- +brew services start fusionauth-search +brew services start fusionauth-app +---- \ No newline at end of file diff --git a/site/docs/v1/tech/shared/_upgrade-using-docker.adoc b/site/docs/v1/tech/shared/_upgrade-using-docker.adoc new file mode 100644 index 0000000000..de64204786 --- /dev/null +++ b/site/docs/v1/tech/shared/_upgrade-using-docker.adoc @@ -0,0 +1,6 @@ +To upgrade FusionAuth when running with `docker-compose`: + +. Stop the instance: `docker-compose down`. +. Modify the `docker-compose.yml` file to point to the version of FusionAuth you want. You can see https://hub.docker.com/r/fusionauth/fusionauth-app[available tags]. +. Start it up: `docker-compose up`. +. Log in to the administrative UI. \ No newline at end of file