|
| 1 | +## Release Highlights |
| 2 | + |
| 3 | +This release contains major upgrades to core components. Detailed upgrade instructions can be found below. |
| 4 | + |
| 5 | +- Infrastructure updates |
| 6 | + - Payara has been upgraded from version 6 to 7 |
| 7 | + - Java has been upgraded from version 17 to 21 |
| 8 | + |
| 9 | +## Upgrade Instructions |
| 10 | + |
| 11 | +### Upgrade from Java 17 to Java 21 |
| 12 | + |
| 13 | +Java 21 is now required to run Dataverse. Solr can run under Java 17 or Java 21 but the latter is recommended and the switch is shown below. In preparation for the Java upgrade, the steps below instruct you to stop both Dataverse (Payara) and Solr. |
| 14 | + |
| 15 | +1. Undeploy Dataverse from Payara 6, if deployed, using the unprivileged service account ("dataverse", by default). |
| 16 | + |
| 17 | + `sudo -u dataverse /usr/local/payara6/bin/asadmin list-applications` |
| 18 | + |
| 19 | + `sudo -u dataverse /usr/local/payara6/bin/asadmin undeploy dataverse-6.9` |
| 20 | + |
| 21 | +1. Stop Payara 6. |
| 22 | + |
| 23 | + `sudo -u dataverse /usr/local/payara6/bin/asadmin stop-domain` |
| 24 | + |
| 25 | +1. Stop Solr. |
| 26 | + |
| 27 | + `sudo systemctl stop solr.service` |
| 28 | + |
| 29 | +1. Install Java 21. |
| 30 | + |
| 31 | + Assuming you are using RHEL or a derivative such as Rocky Linux: |
| 32 | + |
| 33 | + `sudo dnf install java-21-openjdk` |
| 34 | + |
| 35 | +1. Set Java 21 as the default. |
| 36 | + |
| 37 | + Assuming you are using RHEL or a derivative such as Rocky Linux: |
| 38 | + |
| 39 | + `sudo alternatives --config java` |
| 40 | + |
| 41 | +1. Test that Java 21 is the default. |
| 42 | + |
| 43 | + `java -version` |
| 44 | + |
| 45 | +### Upgrade from Payara 6 to Payara 7 |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +The steps below involve carefully transferring your configuration settings from your existing Payara 6 domain directory into the brand new domain from the Payara 7 distribution. You may also want to review the Payara upgrade instructions as it could be helpful during any troubleshooting: |
| 50 | +[Payara Release Notes](https://docs.payara.fish/community/docs/Release%20Notes/Release%20Notes%207.2026.2.html). |
| 51 | +We also recommend you ensure you followed all update instructions from the past releases regarding Payara. |
| 52 | +(The most recent Payara update was for [Dataverse 6.9](https://github.com/IQSS/dataverse/releases/tag/v6.9).) |
| 53 | + |
| 54 | +1. Download Payara 7.2026.2. |
| 55 | + |
| 56 | + `curl -L -O https://nexus.payara.fish/repository/payara-community/fish/payara/distributions/payara/7.2026.2/payara-7.2026.2.zip` |
| 57 | + |
| 58 | +1. Unzip it to /usr/local (or your preferred location). |
| 59 | + |
| 60 | + `sudo unzip payara-7.2026.2.zip -d /usr/local/` |
| 61 | + |
| 62 | +1. Set permission for the service account ("dataverse" by default). |
| 63 | + |
| 64 | + `sudo chown -R root:root /usr/local/payara7` |
| 65 | + `sudo chown dataverse /usr/local/payara7/glassfish/lib` |
| 66 | + `sudo chown -R dataverse:dataverse /usr/local/payara7/glassfish/domains/domain1` |
| 67 | + |
| 68 | +1. Start and stop Payara 7 to let it reformat its domain.xml file. |
| 69 | + |
| 70 | + When Payara starts, it will reformat its domain.xml file, which we will be backing up and editing. By stopping and starting Payara, the `diff` between the backup and the edited file will be easier to read. |
| 71 | + |
| 72 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin start-domain` |
| 73 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin stop-domain` |
| 74 | + |
| 75 | +1. Copy Dataverse-related lines from Payara 6 to Payara 7 domain.xml. |
| 76 | + |
| 77 | + First, back up the Payara 7 domain.xml file we will be editing. |
| 78 | + |
| 79 | + `sudo -u dataverse cp -a /usr/local/payara7/glassfish/domains/domain1/config/domain.xml /usr/local/payara7/glassfish/domains/domain1/config/domain.xml.orig` |
| 80 | + |
| 81 | + Save the Dataverse-related lines from Payara 6 to a text file. Note that "doi" is for legacy settings like "doi.baseurlstring" that should be [converted](https://guides.dataverse.org/en/6.10/installation/config.html#legacy-single-pid-provider-dataverse-pid-datacite-mds-api-url) to modern equivalents if they are still present. |
| 82 | + |
| 83 | + `sudo egrep 'dataverse|doi' /usr/local/payara6/glassfish/domains/domain1/config/domain.xml > lines.txt` |
| 84 | + |
| 85 | + Edit the Payara 7 domain.xml and insert the Dataverse-related lines. More details are below. |
| 86 | + |
| 87 | + `sudo vi /usr/local/payara7/glassfish/domains/domain1/config/domain.xml` |
| 88 | + |
| 89 | + If any JVM options reference the old payara6 path (`/usr/local/payara6`) be sure to change it to payara7. |
| 90 | + |
| 91 | + The lines will appear in two sections, examples shown below (but your content will vary). |
| 92 | + |
| 93 | + Section 1: system properties (under `<server name="server" config-ref="server-config">`) |
| 94 | + |
| 95 | + ``` |
| 96 | + <system-property name="dataverse.db.user" value="dvnuser"></system-property> |
| 97 | + <system-property name="dataverse.db.host" value="localhost"></system-property> |
| 98 | + <system-property name="dataverse.db.port" value="5432"></system-property> |
| 99 | + <system-property name="dataverse.db.name" value="dvndb"></system-property> |
| 100 | + <system-property name="dataverse.mail.system-email" value="noreply@dev1.dataverse.org"></system-property> |
| 101 | + <system-property name="dataverse.mail.mta.host" value="localhost"></system-property> |
| 102 | + ``` |
| 103 | + |
| 104 | + Please note that if your existing `domain.xml` file contains the old-style mail configuration entry that looks like the following... |
| 105 | + |
| 106 | + `<mail-resource auth="false" host="localhost" from="do-not-reply@yourschool.edu" user="dataversenotify" jndi-name="mail/notifyMailSession"></mail-resource>` |
| 107 | + |
| 108 | + ... this may be a good time to replace it with new-style `system-property` entries, using the lines in the example above as a model. See also the section on [SMTP configuration](https://guides.dataverse.org/en/6.10/installation/config.html#smtp-email-configuration) in the guides. |
| 109 | + |
| 110 | + Note: If you used the Dataverse installer, you won't have a `dataverse.db.password` property. See "Create password aliases" below. |
| 111 | + |
| 112 | + Section 2: JVM options (under `<java-config classpath-suffix="" system-classpath="" debug-options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9009">`, the one under `<config name="server-config">`, not under `<config name="default-config">`) |
| 113 | + |
| 114 | + As an example, the following jvm options were encountered and transferred when upgrading a local test server: |
| 115 | + |
| 116 | + ``` |
| 117 | + <jvm-options>-Ddataverse.files.directory=/usr/local/dvn/data</jvm-options> |
| 118 | + <jvm-options>-Ddataverse.files.file.type=file</jvm-options> |
| 119 | + <jvm-options>-Ddataverse.files.file.label=file</jvm-options> |
| 120 | + <jvm-options>-Ddataverse.files.file.directory=/usr/local/dvn/data</jvm-options> |
| 121 | + <jvm-options>-Ddataverse.rserve.host=localhost</jvm-options> |
| 122 | + <jvm-options>-Ddataverse.rserve.port=6311</jvm-options> |
| 123 | + <jvm-options>-Ddataverse.rserve.user=rserve</jvm-options> |
| 124 | + <jvm-options>-Ddataverse.rserve.password=rserve</jvm-options> |
| 125 | + <jvm-options>-Ddataverse.fqdn=dev1.dataverse.org</jvm-options> |
| 126 | + <jvm-options>-Ddataverse.siteUrl=https://dev1.dataverse.org</jvm-options> |
| 127 | + <jvm-options>-Ddataverse.auth.password-reset-timeout-in-minutes=60</jvm-options> |
| 128 | + <jvm-options>-Ddataverse.pid.providers=fake</jvm-options> |
| 129 | + <jvm-options>-Ddataverse.pid.fake.type=FAKE</jvm-options> |
| 130 | + <jvm-options>-Ddataverse.pid.fake.label=Fake DOI Provider</jvm-options> |
| 131 | + <jvm-options>-Ddataverse.pid.fake.authority=10.5072</jvm-options> |
| 132 | + <jvm-options>-Ddataverse.pid.fake.shoulder=FK2/</jvm-options> |
| 133 | + <jvm-options>-Ddataverse.pid.default-provider=fake</jvm-options> |
| 134 | + <jvm-options>-Ddataverse.timerServer=true</jvm-options> |
| 135 | + <jvm-options>-Ddataverse.files.storage-driver-id=file</jvm-options> |
| 136 | + <jvm-options>-Ddataverse.mail.system-email=noreply@dev1.dataverse.org</jvm-options> |
| 137 | + <jvm-options>-Ddataverse.files.uploads=/tmp</jvm-options> |
| 138 | + <jvm-options>-Ddataverse.feature.api-session-auth=0</jvm-options> |
| 139 | + <jvm-options>-Ddataverse.spi.exporters.directory=/var/lib/dataverse/exporters</jvm-options> |
| 140 | + ``` |
| 141 | + |
| 142 | +1. Check the `Xmx` setting in `domain.xml`. |
| 143 | + |
| 144 | + Under `/usr/local/payara7/glassfish/domains/domain1/config/domain.xml`, check the `Xmx` setting under `<config name="server-config">`, where you put the Dataverse-related JVM options, not the one under `<config name="default-config">`. This sets the JVM heap size; a good rule of thumb is half of your system's total RAM. You may specify the value in MB (`8192m`) or GB (`8g`). |
| 145 | + |
| 146 | +1. **Please make sure** to check for any other custom configuration settings you may have in your current `domain.xml` that are not explicitly covered in the sections above. As an example, for Harvard Dataverse we have the thread pool size configured as follows for the main http listener: |
| 147 | + |
| 148 | + `<thread-pool name="http-thread-pool" max-thread-pool-size="400"></thread-pool>` |
| 149 | + |
| 150 | +1. Comment out JSP servlet mappings. |
| 151 | + |
| 152 | + First, backup the file you'll be editing. |
| 153 | + |
| 154 | + `sudo cp -a /usr/local/payara7/glassfish/domains/domain1/config/default-web.xml /usr/local/payara7/glassfish/domains/domain1/config/default-web.xml.orig` |
| 155 | + |
| 156 | + Then, edit the file and follow the instructions below. |
| 157 | + |
| 158 | + `sudo vi /usr/local/payara7/glassfish/domains/domain1/config/default-web.xml` |
| 159 | + |
| 160 | + Comment out the following section and save the file. |
| 161 | + |
| 162 | + ``` |
| 163 | + <servlet-mapping> |
| 164 | + <servlet-name>jsp</servlet-name> |
| 165 | + <url-pattern>*.jsp</url-pattern> |
| 166 | + <url-pattern>*.jspx</url-pattern> |
| 167 | + </servlet-mapping> |
| 168 | + ``` |
| 169 | + |
| 170 | +1. Copy `jhove.conf` and `jhoveConfig.xsd` from Payara 6, edit and change `payara6` to `payara7`. |
| 171 | + |
| 172 | + `sudo bash -c 'cp /usr/local/payara6/glassfish/domains/domain1/config/jhove* /usr/local/payara7/glassfish/domains/domain1/config'` |
| 173 | + |
| 174 | + `sudo bash -c 'chown dataverse /usr/local/payara7/glassfish/domains/domain1/config/jhove*'` |
| 175 | + |
| 176 | + `sudo -u dataverse vi /usr/local/payara6/glassfish/domains/domain1/config/jhove.conf` |
| 177 | + |
| 178 | +1. Copy logos from Payara 6 to Payara 7. |
| 179 | + |
| 180 | + These logos are for collections (dataverses). |
| 181 | + |
| 182 | + `sudo -u dataverse cp -r /usr/local/payara6/glassfish/domains/domain1/docroot/logos /usr/local/payara7/glassfish/domains/domain1/docroot` |
| 183 | + |
| 184 | +1. Copy sitemap from Payara 6 to Payara 7. |
| 185 | + |
| 186 | + It's a good practice to set up a sitemap, but you can skip this step if you don't want one. |
| 187 | + |
| 188 | + If you already have a cron job in place as [recommended](https://guides.dataverse.org/en/6.10/installation/config.html#creating-a-sitemap-and-submitting-it-to-search-engines) by the guides, you could run that cron job manually as a final step, but we recommend copying over your existing sitemap. |
| 189 | + |
| 190 | + `sudo -u dataverse cp -r /usr/local/payara6/glassfish/domains/domain1/docroot/sitemap /usr/local/payara7/glassfish/domains/domain1/docroot` |
| 191 | + |
| 192 | +1. If you are using Make Data Count (MDC), make various updates. |
| 193 | + |
| 194 | + Your `:MDCLogPath` database setting might be pointing to a Payara 6 directory such as `/usr/local/payara6/glassfish/domains/domain1/logs`. If so, use the settings API to change it to point to the payara7 location (once Dataverse is running again): |
| 195 | + |
| 196 | + `curl -X PUT -d '/usr/local/payara7/glassfish/domains/domain1/logs' http://localhost:8080/api/admin/settings/:MDCLogPath` |
| 197 | + |
| 198 | + You'll probably want to copy your logs over as well. |
| 199 | + |
| 200 | + Update Counter Processer to put payara7 in the counter-processor-config.yaml and counter_daily.sh. See https://guides.dataverse.org/en/6.10/admin/make-data-count.html |
| 201 | + |
| 202 | +1. If you've enabled access logging or any other site-specific configuration, be sure to preserve them. For instance, the default domain.xml includes |
| 203 | + |
| 204 | + ``` |
| 205 | + <http-service> |
| 206 | + <access-log></access-log> |
| 207 | + ``` |
| 208 | + |
| 209 | + but you may wish to include |
| 210 | + |
| 211 | + ``` |
| 212 | + <http-service access-logging-enabled="true"> |
| 213 | + <access-log format="%client.name% %datetime% %request% %status% %response.length% %header.user-agent% %header.referer% %cookie.JSESSIONID% %header.x-forwarded-for%"></access-log> |
| 214 | + ``` |
| 215 | + |
| 216 | + Be sure to keep a previous copy of your domain.xml for reference. |
| 217 | + |
| 218 | +1. Update systemd unit file (or other init system) from `/usr/local/payara6` to `/usr/local/payara7`, if applicable. |
| 219 | + |
| 220 | + This example is for systemd: |
| 221 | + |
| 222 | + `sudo vi /usr/lib/systemd/system/payara.service` |
| 223 | + |
| 224 | + See also https://guides.dataverse.org/en/6.10/installation/prerequisites.html#launching-payara-on-system-boot |
| 225 | + |
| 226 | +1. Start Payara 7. |
| 227 | + |
| 228 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin start-domain` |
| 229 | + |
| 230 | +1. Create password aliases for your database, rserve and datacite jvm-options, if you're using them. |
| 231 | + |
| 232 | + `echo "AS_ADMIN_ALIASPASSWORD=yourDBpassword" > /tmp/dataverse.db.password.txt` |
| 233 | + |
| 234 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin create-password-alias --passwordfile /tmp/dataverse.db.password.txt` |
| 235 | + |
| 236 | + When you are prompted "Enter the value for the aliasname operand", enter `dataverse.db.password` |
| 237 | + |
| 238 | + You should see "Command create-password-alias executed successfully." |
| 239 | + |
| 240 | + You'll want to perform similar commands for `rserve_password_alias` and `doi_password_alias` if you're using Rserve and/or DataCite. |
| 241 | + |
| 242 | +1. Create the network listener on port 8009. |
| 243 | + |
| 244 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin create-network-listener --protocol http-listener-1 --listenerport 8009 --jkenabled true jk-connector` |
| 245 | + |
| 246 | +1. Deploy the Dataverse 6.10 war file. |
| 247 | + |
| 248 | + `wget https://github.com/IQSS/dataverse/releases/download/v6.10/dataverse-6.10.war` |
| 249 | + |
| 250 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin deploy dataverse-6.10.war` |
| 251 | + |
| 252 | +1. Check that you get a version number from Dataverse. |
| 253 | + |
| 254 | + This is just a sanity check that Dataverse has been deployed properly. |
| 255 | + |
| 256 | + `curl http://localhost:8080/api/info/version` |
| 257 | + |
| 258 | +1. Perform one final Payara restart to ensure that timers are initialized properly. |
| 259 | + |
| 260 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin stop-domain` |
| 261 | + |
| 262 | + `sudo -u dataverse /usr/local/payara7/bin/asadmin start-domain` |
| 263 | + |
| 264 | +1. Start Solr under Java 21 now that it's the default. |
| 265 | + |
| 266 | + `sudo systemctl start solr.service` |
| 267 | + |
| 268 | +1. For installations with internationalization or text customizations: |
| 269 | + |
| 270 | + Please remember to update translations via [Dataverse language packs](https://github.com/GlobalDataverseCommunityConsortium/dataverse-language-packs). |
| 271 | + |
| 272 | + If you have text customizations you can get the latest English files from <https://github.com/IQSS/dataverse/tree/v6.10/src/main/java/propertyFiles>. |
0 commit comments