small tweaks to upgrade instructions #10646

IQSS · Jul 2, 2024 · b718765 · b718765
1 parent 4cdd6bb
commit b718765
Showing 1 changed file with 46 additions and 41 deletions.
diff --git a/doc/release-notes/6.3-release-notes.md b/doc/release-notes/6.3-release-notes.md
@@ -313,10 +313,10 @@ In the following commands, we assume that Payara 6 is installed in `/usr/local/p
 2\. Stop Payara and remove the following directories:
 
 ```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
+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\. Upgrade Payara to v6.2024.6
@@ -329,63 +329,67 @@ 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)
+[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))
+(The 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.8
+mv $PAYARA $PAYARA.6.2023.8
 ```
 
 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
+cd /usr/local
+unzip payara-6.2024.6.zip
 ```
 
-Replace the brand new payara/glassfish/domains/domain1 with your old, preserved domain1:
+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.8/glassfish/domains/domain1 payara6/glassfish/domains/
+mv payara6/glassfish/domains/domain1 payara6/glassfish/domains/domain1_DIST
+mv payara6-2023.8/glassfish/domains/domain1 payara6/glassfish/domains/
 ```
 
 Make sure that you have the following `--add-opens` options in your `payara6/glassfish/domains/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>
+<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
+sudo service payara start
 ```
 
 4\. Deploy this version.
 
-- `$PAYARA/bin/asadmin deploy dataverse-6.3.war`
+```shell
+$PAYARA/bin/asadmin deploy dataverse-6.3.war
+```
 
 5\. For installations with internationalization:
 
 - Please remember to update translations via [Dataverse language packs](https://github.com/GlobalDataverseCommunityConsortium/dataverse-language-packs).
 
 6\. Restart Payara
 
-- `service payara stop`
-- `service payara start`
+```shell
+service payara stop
+service payara start
+```
 
-7\. Update the following Metadata Blocks to reflect the incremental improvements made to the handling of core metadata fields:
+7\. Update the following metadata blocks to reflect the incremental improvements made to the handling of core metadata fields:
 
- ```
+```shell
 wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/scripts/api/data/metadatablocks/citation.tsv
 
 curl http://localhost:8080/api/admin/datasetfield/load -H "Content-type: text/tab-separated-values" -X POST --upload-file citation.tsv
@@ -402,42 +406,43 @@ curl http://localhost:8080/api/admin/datasetfield/load -H "Content-type: text/ta
 
 8\. Upgrade Solr
 
-Solr 9.4.1 is now the version recommended in our installation guides and used with automated testing. There is a known security issue in the previously recommended version 9.3.0: https://nvd.nist.gov/vuln/detail/CVE-2023-36478. While the risk of an exploit should not be significant unless the Solr instance is accessible from the outside networks (which we have always recommended against), we recommend to upgrade.
+Solr 9.4.1 is now the version recommended in our Installation Guide and used with automated testing. There is a known security issue in the previously recommended version 9.3.0: https://nvd.nist.gov/vuln/detail/CVE-2023-36478. While the risk of an exploit should not be significant unless the Solr instance is accessible from outside networks (which we have always recommended against), we recommend to upgrade.
 
-- Install solr-9.4.1 following the instructions from the Installation guide.
+Install Solr 9.4.1 following the [instructions](https://guides.dataverse.org/en/6.3/installation/prerequisites.html#solr) from the Installation Guide.
 
 The instructions in the guide suggest to use the config files from the installer zip bundle. Upgrading an existing instance, it may be easier to download them from the source tree:
 
 ```shell
-    wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/solrconfig.xml
-    wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/schema.xml
-    cp solrconfig.xml schema.xml /usr/local/solr/solr-9.4.1/server/solr/collection1/conf
+wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/solrconfig.xml
+wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/schema.xml
+cp solrconfig.xml schema.xml /usr/local/solr/solr-9.4.1/server/solr/collection1/conf
 ```
 
-8\. For installations with custom or experimental metadata blocks:
+8a\. For installations with custom or experimental metadata blocks:
 
-- Stop Solr instance (usually `service solr stop`, depending on Solr installation/OS, see the [Installation Guide](https://guides.dataverse.org/en/6.3/installation/prerequisites.html#solr-init-script))
+- Stop Solr instance (usually `service solr stop`, depending on Solr installation/OS, see the [Installation Guide](https://guides.dataverse.org/en/6.3/installation/prerequisites.html#solr-init-script)).
 
-- Run the `update-fields.sh` script that we supply, as in the example below (modify the command lines as needed to reflect the correct path of your solr installation):
-```
-   wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/update-fields.sh
-   chmod +x update-fields.sh
-   curl "http://localhost:8080/api/admin/index/solr/schema" | ./update-fields.sh /usr/local/solr/solr-9.4.1/server/solr/collection1/conf/schema.xml
+- Run the `update-fields.sh` script that we supply, as in the example below (modify the command lines as needed to reflect the correct path of your Solr installation):
+
+```shell
+wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/update-fields.sh
+chmod +x update-fields.sh
+curl "http://localhost:8080/api/admin/index/solr/schema" | ./update-fields.sh /usr/local/solr/solr-9.4.1/server/solr/collection1/conf/schema.xml
 ```
 
-- Start Solr instance (usually `service solr start` depending on solr/OS)
+- Start Solr instance (usually `service solr start` depending on Solr/OS).
 
 9\. Enable the Metadata Source facet for harvested content (Optional):
 
 If you choose to enable this new feature, set the optional feature flag (jvm option) `dataverse.feature.index-harvested-metadata-source=true` before reindexing.
 
-10\. Reindex Solr, if you upgraded Solr, or chose to enable any options that require a reindex:
+10\. Reindex Solr, if you upgraded Solr (recommended), or chose to enable any options that require a reindex:
 
 ```shell
-    curl http://localhost:8080/api/admin/index
+curl http://localhost:8080/api/admin/index
 ```
 
-   Note: if you choose to perform a migration of your `keywordValue` metadata fields (section below), that will require a reindex as well, so do that first.
+Note: if you choose to perform a migration of your `keywordValue` metadata fields (section below), that will require a reindex as well, so do that first.
 
 ## Notes for Dataverse Installation Administrators
 
@@ -446,7 +451,7 @@ If you choose to enable this new feature, set the optional feature flag (jvm opt
 You can migrate your `keywordValue` data containing URIs to the new `keywordTermURI` field.
 In case of data migration, view the affected data with the following database query:
 
-```
+```sql
 SELECT value FROM datasetfieldvalue dfv
 INNER JOIN datasetfield df ON df.id = dfv.datasetfield_id
 WHERE df.datasetfieldtype_id = (SELECT id FROM datasetfieldtype WHERE name = 'keywordValue')
@@ -455,7 +460,7 @@ AND value ILIKE 'http%';
 
 If you wish to migrate your data, a database update is then necessary:
 
-```
+```sql
 UPDATE datasetfield df
 SET datasetfieldtype_id  = (SELECT id FROM datasetfieldtype WHERE name = 'keywordTermURI')
 FROM datasetfieldvalue dfv
@@ -464,6 +469,6 @@ AND df.datasetfieldtype_id = (SELECT id FROM datasetfieldtype WHERE name = 'keyw
 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).
+A [reindex in place](https://guides.dataverse.org/en/latest/admin/solr-search-index.html#reindex-in-place) will be required. 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).
 
 [↑ Table of Contents](#table-of-contents)