docs: upgrade guide improvements

site/_diagrams/docs/admin-guide/blue_green_upgrade.plantuml

@@ -0,0 +1,22 @@
+@startuml
+  !include ../../_config.plantuml
+
+actor "Users" as u
+agent "Load Balancer" as lb
+
+rectangle "Blue Deployment (old version)" as f1 {
+   [Node 1]#lightblue
+   [Node 2]#lightblue
+   [Node 3]#blue;text:white
+}
+
+rectangle "Green Deployment (new version)" as f2 {
+   [Node #1]#lightgreen
+   [Node #2]#lightgreen
+   [Node #3]#lightgreen
+}
+
+u -> lb
+lb -> f1
+lb ..> f2 : Switch traffic when ready
+@enduml

site/_diagrams/docs/admin-guide/rolling_upgrade.plantuml

@@ -0,0 +1,14 @@
+@startuml
+  !include ../../_config.plantuml
+
+actor "Users" as u
+agent "Load Balancer" as lb
+component "Node 1" as n1 #lightgreen
+component "Node 2" as n2 #lightblue
+component "Node 3" as n3 #lightblue
+
+u -> lb
+lb ..> n1 : Switch traffic when ready \n (Upgrade one node at a time)
+lb --> n2
+lb -> n3
+@enduml

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

@@ -1,13 +1,49 @@
 === Templates
 
-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.
+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.
 
 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. Create an link:/docs/v1/tech/apis/authentication#managing-api-keys[API key] with read permissions for Themes in the FusionAuth administrative user interface. Add the API key to the `.env` file. The FusionAuth link:/docs/v1/tech/reference/limitations#default-configuration[default theme has the same 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 copy the link:/docs/v1/tech/reference/limitations#default-configuration[default theme ID `75a068fd-e94b-451a-9aeb-3ddb9a3b5987`] into 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 that show differences between the two sets of theme files and the differences. You can use this list to update your customized theme files. While you can directly use this output to find the changes, it might be useful to use a visual diff tool to help you make the changes, using the file list as a guide.
+
 === 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

@@ -127,6 +127,12 @@ sudo systemctl start fusionauth-app
 net start FusionAuthApp
 ----
 
+
+== FAQs
+
+include::docs/v1/tech/installation-guide/_modes.adoc[]
+
+
 == Runtime Modes
 
 The runtime mode may be configured to trigger or suppress environment specific runtime behavior.

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/_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`.
+. Login to the administrative UI.