Upgrading

Following are the details to upgrade an existing PageSeeder installation.

To upgrade from an old version of PageSeeder, see Upgrading from version 5.6.

To upgrade from a recent beta version, use the following normal procedures. If you have any questions about options for upgrades, contact Allette Systems.

Upgrading to version 6

When upgrading to PageSeeder version 6.x for the first time the following steps must be performed.

Before upgrading

If the server is not already using PageSeeder v5.9913 then upgrade it to this version. To do this on Linux you can use the command:

# yum install pageseeder-5.9913-1

If the following properties are in [pageseeder]/webapp/WEB-INF/config/global.properties and don’t have the valuesdocumentPort=80 and documentScheme=http then remove them, run the following SQL and restart PageSeeder:

update DGROUPURI set port=80, scheme='http' where hostid=1;

update URI set port=80, scheme='http' where hostid=1;

Use the Templates > Validate page under System administration to find and remove all obsolete and deprecated options from configuration files. Some common validation errors are as follows:

document-template.psml / media-template.psml / url-template.psml

The property element "[x]" has a count attribute which is deprecated (use multiple="true" attribute if required): It’s usually safe to replace count="n" with multiple="true".

The property element "[x]" can not have a @value attribute...: If the datatype is xref, link, markdown or markup it’s safe to remove the value attribute.

document-config.xml

Attribute 'overwrite' is not allowed to appear in element 'publishing': It's safe to change the overwrite attribute to override.

build.xml

The namespace "antlib:com.pageseeder.external.ant" is obsolete, use "antlib:com.pageseeder.publishapi.ant" instead.: It’s safe to replace com.pageseeder.external.ant with com.pageseeder.publishapi.ant

The import element containing '/ant-library/' is obsolete, use current Ant tasks instead.: It’s safe to remove this <import> element.

The depends="psinit.clean-working-folder" attribute on target [x] is obsolete and must be removed. It is no longer required.: It’s safe to remove depends="psinit.clean-working-folder".

The process @includes attribute in target [x] is obsolete, use include elements with @name instead.: It’s safe to replace includes  attribute with the include element. For example replace <xrefs includes="[y]" ...> with <xrefs ...><include name="[y]"/>.

The export/@resolveimages attribute in target psml-to-pdf-columns is obsolete, use loadimages attribute instead.: It’s safe to change the resolveimages attribute to loadimages.

publish-config.xml

A 'source' element with type="document" must have an 'extension' attribute.: It’s usually safe to add extension="psml" as scripts usually apply to PSML documents.

word-import-config.xml

Invalid content was found starting with element 'document'. One of '{mathml, footnotes, endnotes}' is expected.: It’s usually safe to remove <document> and <section> elements under <split> as splitting is usually done by the split-config.xml.

Use the Logs > General logs page under System administration to check for any warning in the past few weeks such as:

Request to service/servlet deprecated - update the app making the request to use non-deprecated services/servlets.

The path /ps/ws/uris/[ID] could not be found on this web server - configure WebSockets on NGINX as descibed in the following Linux upgrade steps.

If smtpServerAddress=localhost in [pageseeder]/webapp/WEB-INF/config/global.properties outgoing email will no longer work (the value can be checked under System configuration > Server properties). In that case this property must be changed to either:

blank, which will disable outgoing email (for example in local development), or

an external email server or email provider such as Gmail, Mailgun or SendGrid. If the email provider requires SSL or START TLS set this up using the new System configuration > Email settings page after upgrading PageSeeder but set up an account with the provider now to save time.

Install Java 11 on the server as described for Windows or Linux in the following.

After upgrading

If using the MySQL database, before starting PageSeeder, install Connector/J v8.0.23 or higher as described for Windows or Linux in the following.

After starting PageSeeder all groups and URLs must be re-indexed as follows. Many features will not work on PageSeeder until re-indexing is finished.

On a production server with thousands of documents or URLs you should enter a message like the following under Server message on the System administration dashboard This server is being re-indexed, search may not be available in some groups. and click Post.

Go to the Server status > Indexing page, ensure that Everything is selected, click Start Indexing and wait until indexing is finished.

If you posted a message in (1) click Clear under Server message on the System administration dashboard.

Windows

To upgrade from version 5.7 or higher follow these steps:

If not installed already, install Java 11 (or Java 1.8.0 for PageSeeder v5 — see which version of java) as follows:

• Go to https://www.oracle.com/java  and choose Download Java and Java SE.
• Download the JDK or JRE .exe for windows (x64 for 64 bit) and run it.

Stop the PageSeeder windows service (if there is one).

Download the latest pageseeder-x.exe file, available under the Install folder on the Download page and run it.

Once the install commences, follow the instructions provided by the on-screen prompts.

When first upgrading to version 6, update the MySQL JDBC driver (if using MySQL) as follows.

Downloaded Connector/J v8.0.23 or higher from https://www.mysql.com  . Subject to Oracle/MySQL website changes, Connector/J is under ‘MySQL Community Downloads’ and older versions are listed under ‘Archive’.

Replace the mysql-connector-java-5.x.x.jar file with the mysql-connector-java-8.x.x.jar file under [pageseeder]/webapp/WEB-INF/lib and [pageseeder]/webapp/WEB-INF/drivers.

Modify [pageseeder]/webapp/WEB-INF/config/database.properties to have DBDriver=com.mysql.cj.jdbc.Driver.

Linux

To upgrade from version 5.7 or higher, follow these steps:

If not installed already, install Java 11 (or Java 1.8.0 for PageSeeder v5 — see which version of java). To upgrade to Open JDK 11 enter the following and for alternatives select java-11-openjdk:

$ sudo yum install java-11-openjdk
$ sudo alternatives --config java

Stop the PageSeeder service as follows:

$ sudo service pageseeder stop

Install the latest PageSeeder production version as follows:

$ sudo yum update pageseeder

To upgrade to a beta version use rpm and remove hyphens from the version identifier. So, if the source version is called: 
5.9600-beta-4
change it to this:
5.9600~beta4
fully expanded, the version name should follow this pattern: 
pageseeder-5.9600~beta4-1.noarch.rpm

So, to upgrade to a beta PageSeeder, use the following URL but replace [ver.num~ber] with a valid beta identifier:

$ sudo rpm -Uvh https://download.pageseeder.com/pub/rpm/beta/pageseeder-[ver.num~ber]-1.noarch.rpm

When first upgrading to version 6, configure Tomcat as follows (keep pressing Enter when prompted to accept existing values):

$ sudo service pageseeder config

When first upgrading from 5.98 or earlier configure WebSockets on any system using a proxy.

NGINX admins must add the following after the last proxy_set_header line in your current config file (e.g. /etc/nginx/nginx.conf )

      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $http_connection;
      proxy_http_version 1.1;

After saving the file, enter:

$ sudo service nginx restart

When first upgrading to version 6, update the MySQL JDBC driver (if using MySQL) as follows.

Use the following commands to download Connector/J v8.0.23 or higher (URL and version might have changed):

$ wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.29.tar.gz
$ tar xzvf mysql-connector-java-8.0.29.tar.gz

Replace the mysql-connector-java-5.x.x.jar file with the mysql-connector-java-8.x.x.jar file under /opt/pageseeder/webapp/WEB-INF/lib and /opt/pageseeder/webapp/WEB-INF/drivers. Ensure the old file is deleted and that the file permissions are set correctly as follows (version depends on what was downloaded).

$ cd mysql-connector-java-8.0.29
$ cp mysql-connector-java-8.0.29.jar /opt/pageseeder/webapp/WEB-INF/lib
$ cp mysql-connector-java-8.0.29.jar /opt/pageseeder/webapp/WEB-INF/drivers
$ cd /opt/pageseeder/webapp/WEB-INF/lib
$ rm mysql-connector-java-5*
$ chown pageseeder:pageseeder mysql*
$ cd /opt/pageseeder/webapp/WEB-INF/drivers
$ rm mysql-connector-java-5*
$ chown pageseeder:pageseeder mysql*

Modify /opt/pageseeder/webapp/WEB-INF/config/database.properties by updating DBDriver and removing ?useSSL=false from DBURL as follows:

DBDriver=com.mysql.cj.jdbc.Driver
DBURL=jdbc:mysql://localhost/pageseeder

Start the PageSeeder service as follows:

$ sudo service pageseeder start

After the update, it might take a few minutes for the database to start. To check the progress, or if PageSeeder fails to start, view the log file.

$ cat /opt/pageseeder/webapp/WEB-INF/state/logs/general/general.log

Reverting an upgrade

If there is a problem caused by the upgrade and it is only a maintenance upgrade then you MAY be able to revert the upgrade in Linux using the command yum downgrade pageseeder-[version]-1after stopping PageSeeder. For example to revert to version 6.0009 use commands like:

$ sudo service pageseeder stop
$ sudo yum downgrade pageseeder-6.0009-1