moved payara upgrade into the main upgrade instruction #10646

Author: landreev

doc/release-notes/6.3-release-notes.md

@@ -276,6 +276,8 @@ These instructions assume that you've already upgraded through all the 5.x relea
 
 0\. These instructions assume that you are upgrading from the immediate previous version. If you are running an earlier version, the only safe way to upgrade is to progress through the upgrades to all the releases in between before attempting the upgrade to this version.
 
+Upgrading requires a maintenance window and downtime. Please plan ahead, create backups of your database, etc.
+
 If you are running Payara as a non-root user (and you should be!), **remember not to execute the commands below as root**. Use `sudo` to change to that user first. For example, `sudo -i -u dataverse` if `dataverse` is your dedicated application user.
 
 In the following commands, we assume that Payara 6 is installed in `/usr/local/payara6`. If not, adjust as needed.
@@ -288,14 +290,65 @@ In the following commands, we assume that Payara 6 is installed in `/usr/local/p
 
 - `$PAYARA/bin/asadmin undeploy dataverse-6.2`
 
-2\. Stop Payara and remove the generated directory
+2\. Stop Payara and remove the following directories:
 
-- `service payara stop`
-- `rm -rf $PAYARA/glassfish/domains/domain1/generated`
+```shell
+   service payara stop
+   rm -rf $PAYARA/glassfish/domains/domain1/generated
+   rm -rf $PAYARA/glassfish/domains/domain1/osgi-cache
+   rm -rf $PAYARA/glassfish/domains/domain1/lib/databases
+```
 
-3\. Start Payara
+3\. Upgrade Payara to v6.2024.6
 
-- `service payara start`
+With this version of Dataverse, we encourage you to upgrade to version 6.2024.6.
+This will address security issues accumulated since the release of 6.2023.8.
+
+Note that if you are using GDCC containers, this upgrade is included when pulling new release images.
+No manual intervention is necessary.
+
+The steps below are a simple matter of reusing your existing domain directory with the new distribution.
+But we recommend that you review the Payara upgrade instructions as it could be helpful during any troubleshooting:
+[Payara Release Notes](https://docs.payara.fish/community/docs/Release%20Notes/Release%20Notes%206.2024.6.html)
+We also recommend you ensure you followed all update instructions from the past releases regarding Payara.
+(Latest Payara update was for [v6.0](https://github.com/IQSS/dataverse/releases/tag/v6.0))
+
+Move the current Payara directory out of the way:
+
+```shell
+    mv $PAYARA $PAYARA.6.2023.6
+```
+
+Download the new Payara version 6.2024.6 (from https://www.payara.fish/downloads/payara-platform-community-edition/), and unzip it in its place:
+
+```shell
+    cd /usr/local 
+    unzip payara-6.2024.6.zip
+```
+
+Replace the brand new payara/glassfish/domains/domain1 with your old, preserved domain1:
+
+```shell
+    mv payara6/glassfish/domains/domain1 payara6/glassfish/domains/domain1_DIST
+    mv payara6-2023.6/glassfish/domains/domain1 payara6/glassfish/domains/
+```
+
+Make sure that you have the following `--add-opens` options in your `domain1/config/domain.xml`. If not present, add them:
+
+```
+         <jvm-options>--add-opens=java.management/javax.management=ALL-UNNAMED</jvm-options>
+         <jvm-options>--add-opens=java.management/javax.management.openmbean=ALL-UNNAMED</jvm-options>
+         <jvm-options>[17|]--add-opens=java.base/java.io=ALL-UNNAMED</jvm-options>
+         <jvm-options>[21|]--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED</jvm-options>
+```
+
+(Note that you likely already have the `java.base/java.io` option there, but without the `[17|]` prefix. Make sure to replace it with the version above)
+
+Start Payara: 
+
+```shell
+    sudo service payara start
+```
 
 4\. Deploy this version.
 
@@ -379,87 +432,4 @@ AND dfv.value ILIKE 'http%';
 
 A ['Reindex in Place'](https://guides.dataverse.org/en/latest/admin/solr-search-index.html#reindex-in-place) will be required and ReExportAll will need to be run to update the metadata exports of the dataset. Follow the directions in the [Admin Guide](http://guides.dataverse.org/en/latest/admin/metadataexport.html#batch-exports-through-the-api).
 
-## Upgrade Payara to v6.2024.6
-
-With this version of Dataverse, we encourage you to upgrade to version 6.2024.6.
-This will address security issues accumulated since the release of 6.2023.8, which was required since Dataverse release 6.0.
-
-### Instructions for Upgrading
-
-If you are using GDCC containers, this upgrade is included when pulling new release images.
-No manual intervention is necessary.
-
-We recommend you ensure you followed all update instructions from the past releases regarding Payara.
-(Latest Payara update was for [v6.0](https://github.com/IQSS/dataverse/releases/tag/v6.0))
-
-Upgrading requires a maintenance window and downtime. Please plan ahead, create backups of your database, etc.
-
-The steps below are a simple matter of reusing your existing domain directory with the new distribution.
-But we also recommend that you review the Payara upgrade instructions as it could be helpful during any troubleshooting:
-[Payara Release Notes](https://docs.payara.fish/community/docs/Release%20Notes/Release%20Notes%206.2024.6.html)
-We assume you are already on a Dataverse 6.x installation, using a Payara 6.x release.
-
-```shell
-export PAYARA=/usr/local/payara6
-```
-
-(or `setenv PAYARA /usr/local/payara6` if you are using a `csh`-like shell)
-
-1\. Undeploy the previous version
-
-```shell
-    $PAYARA/bin/asadmin list-applications
-    $PAYARA/bin/asadmin undeploy dataverse<-version>
-```
-
-2\. Stop Payara
-
-```shell
-    service payara stop
-    rm -rf $PAYARA/glassfish/domains/domain1/generated
-    rm -rf $PAYARA/glassfish/domains/domain1/osgi-cache
-    rm -rf $PAYARA/glassfish/domains/domain1/lib/databases
-```
-
-3\. Move the current Payara directory out of the way
-
-```shell
-    mv $PAYARA $PAYARA.MOVED
-```
-
-4\. Download the new Payara version (6.2024.6), and unzip it in its place
-
-5\. Replace the brand new payara/glassfish/domains/domain1 with your old, preserved domain1
-
-6\. Make sure that you have the following `--add-opens` options in your domain.xml. If not present, add them:
-
-```
-         <jvm-options>--add-opens=java.management/javax.management=ALL-UNNAMED</jvm-options>
-         <jvm-options>--add-opens=java.management/javax.management.openmbean=ALL-UNNAMED</jvm-options>
-         <jvm-options>[17|]--add-opens=java.base/java.io=ALL-UNNAMED</jvm-options>
-         <jvm-options>[21|]--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED</jvm-options>
-```
-
-(Note that you likely already have the `java.base/java.io` option there, but without the `[17|]` prefix. Make sure to replace it with the version above)
-
-
-7\. Start Payara
-
-```shell
-    service payara start
-```
-
-8\. Deploy this version.
-
-```shell
-    $PAYARA/bin/asadmin deploy dataverse-6.3.war
-```
-
-9\. Restart payara
-
-```shell
-    service payara stop
-    service payara start
-```
-
 [↑ Table of Contents](#table-of-contents)