Mooreds/1951 upgrade guide (#2461)

Upgrade guide overhaul

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
+
+|===
+

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[]

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.

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.
 

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
 

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.
 - <<Maintenance Mode>>
 - <<Advanced Installation>>
 - <<Troubleshooting>>
+- <<FAQs>>
 
 == 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 <<Start FusionAuth App>> section above.
 
 include::docs/v1/tech/installation-guide/_troubleshooting-runtime-modes-at-startup.adoc[]
 
+== FAQs
+
+include::docs/v1/tech/installation-guide/_modes.adoc[]
+

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[]

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
 

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

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.