publish upgrade guide

en/success-guide/update_cert.md

@@ -1,14 +1,14 @@
 ---
 layout: default
 lang: en
-nav_link: Update Certificates
+nav_link: Certificate Update
 nav_level: 2
 nav_order: 330
 ---
 
 # Updating Public/Private Certificates
 
-[Previous Section](scheduling.md) \| [Back to Contents](index.md) 
+[Previous Section](scheduling.md) \| [Next Section](upgrading.md) 
 
 The [Adobe Developer Console certificates](setup_adobeio.md) you created during initial setup will eventually expire and
 need replacement. Adobe will notify all system admins for an organization when one or more certificates are set to expire.
@@ -25,7 +25,7 @@ You can generate a new public/private keypair in the Adobe Developer console. **
 privileges in the Admin Console organization associated with your keys.
 
 1. Log into [Adobe Developer Console](https://developer.adobe.com/console)
-2. Make sure you select the correct organization in the dropdown menu in the upper-left-hand corner of the page
+2. Make sure you select the correct organization in the dropdown menu in the upper-right-hand corner of the page
 3. Click the "Projects" tab in the top navigation menu
 4. Click the card for the project associated with the credentials you wish to update
 
@@ -69,3 +69,5 @@ Return to the [Adobe Developer Console](https://developer.adobe.com/console), op
 Service Account details, and click the trash icon next to the old public key.
 
 ![](images/delete_old_key.png)
+
+[Previous Section](scheduling.md) \| [Next Section](upgrading.md) 

en/success-guide/upgrading.md

@@ -0,0 +1,113 @@
+---
+layout: default
+lang: en
+nav_link: Upgrade Guide
+nav_level: 2
+nav_order: 340
+---
+
+# Upgrade From PEX to Binary
+{:."no_toc"}
+
+## In This Section
+{:."no_toc"}
+
+* TOC Placeholder
+{:toc}
+
+---
+
+[Previous Section](update_cert.md) \| [Back to Contents](index.md)
+
+---
+
+# Why Upgrade?
+
+To ensure security and stability, the development team of the User Sync Tool does not support older versions of the Sync
+Tool. We encourage every user of the tool check for [new releases](https://github.com/adobe-apiplatform/user-sync.py/releases/latest)
+regularly and keep their User Sync Tool up-to-date.
+
+Any User Sync Tool release prior to 2.6.0 is packaged as a [pex](https://github.com/pantsbuild/pex) file, which requires an
+external Python interpreter to run. To maximize compatibility, builds were targeted to Python 2.7 and Python 3.6 (or below).
+Starting with 2.6.0, the sync tool is built and distributed as a self-contained binary executable. This executable embeds its
+own Python environment, removing the requirement of an external Python interpreter.
+
+This build model also makes it possible for the UST to be built with newer versions of Python. The executable build currently
+runs with Python 3.9 (as of version 2.6.5). Older versions of Python are either no longer maintained, or are
+[nearing end-of-life](https://endoflife.date/python).
+
+The User Sync Tool also has many new features unavailable in older versions.
+
+* Instant access to documentation - `./user-sync docs`
+* Security key generation - `./user-sync certgen`
+* Private key encryption and decryption - `./user-sync encrypt` and `./user-sync decrypt`
+* Template config generation - `./user-sync example-config`
+* LDAP Kerberos Support
+* Admin Console identity connector
+* Adobe Sign Sync capability
+* See the [changelog](https://raw.githubusercontent.com/adobe-apiplatform/user-sync.py/v2/.changelog/changelog.md) for more details
+
+# Compatibility
+
+The binary build of the UST has been tested on the supported versions of our targeted platforms (Windows, CentOS and Ubuntu). It is
+compatible with all major versions except for older Ubuntu LTS releases.
+
+Neither the Bionic nor Focal builds will run on Ubuntu Trusty or Xenial because each of the former require newer versions of `libc`.
+It may be possible to upgrade libc and other system packages to get the tool running, but the UST development team will not be able to
+provide support.
+
+The tool can also be built from source to run on unsupported platforms. See the [build instructions](https://github.com/adobe-apiplatform/user-sync.py#build-instructions)
+in the readme. Note that Python 3.9 is required to build the tool, which may need to be installed on the system (or built from source).
+
+| Platform | Compatible? | Notes |
+|---|---|---|
+| Windows Server 2012R2 | Y | |
+| Windows Server 2016 | Y | |
+| Windows Server 2019 | Y | |
+| CentOS/RedHat Enterprise Linux 7 | Y | |
+| CentOS/RedHat Enterprise Linux 8 | Y | |
+| Ubuntu Trusty 12.04 | N | `bionic` or `focal` builds will not run on Trusty and it [isn't supported by our build system](https://github.com/actions/virtual-environments) |
+| Ubuntu Xenial 16.04 | N | `bionic` or `focal` builds will not run on Xenial and it [isn't supported by our build system](https://github.com/actions/virtual-environments) |
+| Ubuntu Bionic 18.04 | Y | Use `ubuntu-bionic` build |
+| Ubuntu Focal 20.04 | Y | Use `ubuntu-focal` build |
+{: .bordertablestyle }
+
+# Basic Procedure
+
+**Note:** If you run multiple sync processes (perhaps to sync from different identity sources), we recommend repeating this procedure
+for each sync config. You will not need to repeat steps 1 and 2 if each sync is run from the same root directory.
+
+1. Download the [latest release](https://github.com/adobe-apiplatform/user-sync.py/releases/latest) for your platform.
+2. Extract the release archive and copy the `user-sync` (or `user-sync.exe`) binary to the system's sync tool directory.
+3. Run the sync tool in test mode.
+    1. Open command-line terminal
+    2. `cd /path/to/ust`
+    3. Run the command you would use to make a live sync, but running the UST executable and appending the `-t` command-line option
+
+       This is the command you would run from the cron job/scheduled task, or the associated shell script/batch file
+
+       **Linux example** -- if the command to run the tool in live mode is `python user-sync.pex --process-groups --users mapped`
+       then the command to test the new binary version is `./user-sync --process-groups --users mapped -t`
+
+       **Windows example** -- using the pex-based command in the Linux example, the command to test the Windows EXE is
+       `.\user-sync.exe --process-groups --users mapped -t`
+4. Compare log output from test run to log output from previous live run.
+
+   There isn't an exact procedure we can outline here -- each UST installation is different. In general, look at the counts in the
+   sync summary and make sure they aren't radically different. Look at the log messages for any errors or anomalous behavior.
+
+   Note that log messages in the test run may be worded differently or may appear in a different order.
+
+   If you need help, please [reach out](#getting-help).
+
+5. IF the test logs look good, update the sync command in the cron job/scheduled task or associated script.
+
+   Use the same command you used to test the file with the test mode flag (`-t`) removed.
+
+   Check the UST logs after the next time it runs to ensure it behaves as expected.
+
+# Getting Help
+
+Please [create an issue](https://github.com/adobe-apiplatform/user-sync.py/issues) if you need help with the upgrade process.
+
+[Previous Section](update_cert.md) \| [Back to Contents](index.md)