Skip to content

Commit b718765

Browse files
committed
small tweaks to upgrade instructions #10646
1 parent 4cdd6bb commit b718765

File tree

1 file changed

+46
-41
lines changed

1 file changed

+46
-41
lines changed

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

+46-41
Original file line numberDiff line numberDiff line change
@@ -313,10 +313,10 @@ In the following commands, we assume that Payara 6 is installed in `/usr/local/p
313313
2\. Stop Payara and remove the following directories:
314314

315315
```shell
316-
service payara stop
317-
rm -rf $PAYARA/glassfish/domains/domain1/generated
318-
rm -rf $PAYARA/glassfish/domains/domain1/osgi-cache
319-
rm -rf $PAYARA/glassfish/domains/domain1/lib/databases
316+
service payara stop
317+
rm -rf $PAYARA/glassfish/domains/domain1/generated
318+
rm -rf $PAYARA/glassfish/domains/domain1/osgi-cache
319+
rm -rf $PAYARA/glassfish/domains/domain1/lib/databases
320320
```
321321

322322
3\. Upgrade Payara to v6.2024.6
@@ -329,63 +329,67 @@ No manual intervention is necessary.
329329

330330
The steps below are a simple matter of reusing your existing domain directory with the new distribution.
331331
But we recommend that you review the Payara upgrade instructions as it could be helpful during any troubleshooting:
332-
[Payara Release Notes](https://docs.payara.fish/community/docs/Release%20Notes/Release%20Notes%206.2024.6.html)
332+
[Payara Release Notes](https://docs.payara.fish/community/docs/Release%20Notes/Release%20Notes%206.2024.6.html).
333333
We also recommend you ensure you followed all update instructions from the past releases regarding Payara.
334-
(Latest Payara update was for [v6.0](https://github.com/IQSS/dataverse/releases/tag/v6.0))
334+
(The latest Payara update was for [v6.0](https://github.com/IQSS/dataverse/releases/tag/v6.0).)
335335

336336
Move the current Payara directory out of the way:
337337

338338
```shell
339-
mv $PAYARA $PAYARA.6.2023.8
339+
mv $PAYARA $PAYARA.6.2023.8
340340
```
341341

342342
Download the new Payara version 6.2024.6 (from https://www.payara.fish/downloads/payara-platform-community-edition/), and unzip it in its place:
343343

344344
```shell
345-
cd /usr/local
346-
unzip payara-6.2024.6.zip
345+
cd /usr/local
346+
unzip payara-6.2024.6.zip
347347
```
348348

349-
Replace the brand new payara/glassfish/domains/domain1 with your old, preserved domain1:
349+
Replace the brand new `payara/glassfish/domains/domain1` with your old, preserved domain1:
350350

351351
```shell
352-
mv payara6/glassfish/domains/domain1 payara6/glassfish/domains/domain1_DIST
353-
mv payara6-2023.8/glassfish/domains/domain1 payara6/glassfish/domains/
352+
mv payara6/glassfish/domains/domain1 payara6/glassfish/domains/domain1_DIST
353+
mv payara6-2023.8/glassfish/domains/domain1 payara6/glassfish/domains/
354354
```
355355

356356
Make sure that you have the following `--add-opens` options in your `payara6/glassfish/domains/domain1/config/domain.xml`. If not present, add them:
357357

358358
```
359-
<jvm-options>--add-opens=java.management/javax.management=ALL-UNNAMED</jvm-options>
360-
<jvm-options>--add-opens=java.management/javax.management.openmbean=ALL-UNNAMED</jvm-options>
361-
<jvm-options>[17|]--add-opens=java.base/java.io=ALL-UNNAMED</jvm-options>
362-
<jvm-options>[21|]--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED</jvm-options>
359+
<jvm-options>--add-opens=java.management/javax.management=ALL-UNNAMED</jvm-options>
360+
<jvm-options>--add-opens=java.management/javax.management.openmbean=ALL-UNNAMED</jvm-options>
361+
<jvm-options>[17|]--add-opens=java.base/java.io=ALL-UNNAMED</jvm-options>
362+
<jvm-options>[21|]--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED</jvm-options>
363363
```
364364

365365
(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)
366366

367367
Start Payara:
368368

369369
```shell
370-
sudo service payara start
370+
sudo service payara start
371371
```
372372

373373
4\. Deploy this version.
374374

375-
- `$PAYARA/bin/asadmin deploy dataverse-6.3.war`
375+
```shell
376+
$PAYARA/bin/asadmin deploy dataverse-6.3.war
377+
```
376378

377379
5\. For installations with internationalization:
378380

379381
- Please remember to update translations via [Dataverse language packs](https://github.com/GlobalDataverseCommunityConsortium/dataverse-language-packs).
380382

381383
6\. Restart Payara
382384

383-
- `service payara stop`
384-
- `service payara start`
385+
```shell
386+
service payara stop
387+
service payara start
388+
```
385389

386-
7\. Update the following Metadata Blocks to reflect the incremental improvements made to the handling of core metadata fields:
390+
7\. Update the following metadata blocks to reflect the incremental improvements made to the handling of core metadata fields:
387391

388-
```
392+
```shell
389393
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/scripts/api/data/metadatablocks/citation.tsv
390394

391395
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
402406

403407
8\. Upgrade Solr
404408

405-
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.
409+
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.
406410

407-
- Install solr-9.4.1 following the instructions from the Installation guide.
411+
Install Solr 9.4.1 following the [instructions](https://guides.dataverse.org/en/6.3/installation/prerequisites.html#solr) from the Installation Guide.
408412

409413
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:
410414

411415
```shell
412-
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/solrconfig.xml
413-
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/schema.xml
414-
cp solrconfig.xml schema.xml /usr/local/solr/solr-9.4.1/server/solr/collection1/conf
416+
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/solrconfig.xml
417+
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/schema.xml
418+
cp solrconfig.xml schema.xml /usr/local/solr/solr-9.4.1/server/solr/collection1/conf
415419
```
416420

417-
8\. For installations with custom or experimental metadata blocks:
421+
8a\. For installations with custom or experimental metadata blocks:
418422

419-
- 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))
423+
- 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)).
420424

421-
- 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):
422-
```
423-
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/update-fields.sh
424-
chmod +x update-fields.sh
425-
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
425+
- 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):
426+
427+
```shell
428+
wget https://raw.githubusercontent.com/IQSS/dataverse/v6.3/conf/solr/update-fields.sh
429+
chmod +x update-fields.sh
430+
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
426431
```
427432

428-
- Start Solr instance (usually `service solr start` depending on solr/OS)
433+
- Start Solr instance (usually `service solr start` depending on Solr/OS).
429434

430435
9\. Enable the Metadata Source facet for harvested content (Optional):
431436

432437
If you choose to enable this new feature, set the optional feature flag (jvm option) `dataverse.feature.index-harvested-metadata-source=true` before reindexing.
433438

434-
10\. Reindex Solr, if you upgraded Solr, or chose to enable any options that require a reindex:
439+
10\. Reindex Solr, if you upgraded Solr (recommended), or chose to enable any options that require a reindex:
435440

436441
```shell
437-
curl http://localhost:8080/api/admin/index
442+
curl http://localhost:8080/api/admin/index
438443
```
439444

440-
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.
445+
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.
441446

442447
## Notes for Dataverse Installation Administrators
443448

@@ -446,7 +451,7 @@ If you choose to enable this new feature, set the optional feature flag (jvm opt
446451
You can migrate your `keywordValue` data containing URIs to the new `keywordTermURI` field.
447452
In case of data migration, view the affected data with the following database query:
448453

449-
```
454+
```sql
450455
SELECT value FROM datasetfieldvalue dfv
451456
INNER JOIN datasetfield df ON df.id = dfv.datasetfield_id
452457
WHERE df.datasetfieldtype_id = (SELECT id FROM datasetfieldtype WHERE name = 'keywordValue')
@@ -455,7 +460,7 @@ AND value ILIKE 'http%';
455460

456461
If you wish to migrate your data, a database update is then necessary:
457462

458-
```
463+
```sql
459464
UPDATE datasetfield df
460465
SET datasetfieldtype_id = (SELECT id FROM datasetfieldtype WHERE name = 'keywordTermURI')
461466
FROM datasetfieldvalue dfv
@@ -464,6 +469,6 @@ AND df.datasetfieldtype_id = (SELECT id FROM datasetfieldtype WHERE name = 'keyw
464469
AND dfv.value ILIKE 'http%';
465470
```
466471

467-
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).
472+
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).
468473

469474
[↑ Table of Contents](#table-of-contents)

0 commit comments

Comments
 (0)