New installation on el8/el9

Once the prerequisites described in New installation have been performed the following instructions can be used for a new PageSeeder installation on el8/el9 (enterprise linux v8 or v9, for example Rocky v8 or v9).

Files and folders

The following are key files and folders installed by PageSeeder.

Prerequisites

You must have root permissions on the server.

Before you install PageSeeder, we recommend that you:

1. Install Java (see steps)
2. Ensure that firewalld is running (see Troubleshooting)
3. Install the database server locally (optional)

The installation process can be automated if you have the following details:

1. PageSeeder licence for your host
2. Details of the SMTP server
3. Details of the database to connect to, OR the database administrator details to create a new database

Steps

Before you start

If Java isn't installed, enter the following to install Java 21 (see Which version of Java):

# dnf -y install java-21-openjdk

If you intend to run the database server, you need to install it before you install PageSeeder:

• Configuring MySQL
• Configuring PostgreSQL

Apply for a PageSeeder licence:

• You can apply online to get a 90 day evaluation license  for another domain.
• To license PageSeeder for a production environment, send an email general_info@allette.com.au
• All licenses are bound to a URL, for example, ps.example.com, so any request email must include the intended URL for the PageSeeder server.

Download the database driver

If you haven’t already done so download the latest database driver (URLs and versions might have changed).

If you intend to use MySQL:

# wget https://downloads.mysql.com/archives/get/p/3/file/mysql-connector-j-8.4.0.tar.gz
# tar xzvf mysql-connector-java-8.4.0.tar.gz --wildcards '*.jar'

If you intend to use PostgreSQL:

$ curl -LO https://jdbc.postgresql.org/download/postgresql-42.7.4.jar

Install PageSeeder RPM repo

Use the following to install the PageSeeder Yum repository on your VM (use el8 if you are on Rocky v8):

# rpm -Uvh https://download.pageseeder.com/pub/rpm/pageseeder-repository-1.3-1.el9.noarch.rpm

Install PageSeeder

Install PageSeeder with:

# dnf install pageseeder

This will:

• Install PageSeeder using the default setting in /opt/pageseeder.
• Configure the PageSeeder mail (SMTP) port set to 2525.
• Configure the PageSeeder web (HTTP) port set to 8282.
• Create the pageseeder user.
• Update firewalld to forward port 25 to 2525.
• Set up PageSeeder as a service on systemd.

# update-crypto-policies --set LEGACY
# dnf install pageseeder --nogpgcheck
# update-crypto-policies --set DEFAULT

Start the service

# systemctl start pageseeder

Configure PageSeeder

There are several options to configure PageSeeder

• Use option A for a fresh new installation
• Use option B for a migration or a new installation based on an existing solution
• Use option C for more complex installations or older versions of PageSeeder

Automated setup

The configure script lets you configure PageSeeder using command-line options. If there are are many options, you can save all these options in file.

Create an options.conf file and fill up with the values. Here is a typical options file to create:

# Required for the licence
--website-address=ps.example.org
--product-key=xxxxxxxxxxxxxxxxxx
--email-domain=example.org

# The database details
--update-database
--db-type=PostgreSQL
--db-host=localhost
--db-name=pageseeder
--db-username=pageseeder
--db-password=xxxxxxxx

# The credentials of the database admninistrator
--create-database
--dba-username=postgres
--dba-password=xxxxxxxx

# The details for the PageSeeder administrator to create 
--admin-firstname=Drew
--admin-surname=Smith
--admin-email=dsmith@example.org
--admin-username=dsmith
--admin-password=xxxxxxxx

Then run the following script to configure and setup PageSeeder (the database driver must be in the current directory):

$ /opt/pageseeder/bin/setup.sh -f options.conf

Automated import

On the original system, you can use to export the global.properties, database.properties, and JDBC driver file (in drivers ) and save them into a directory:

$ /opt/pageseeder/bin/setup.sh --export=/tmp/ps-export

If the export option is not available, you can do this manually, copy the following files:

• /opt/pageseeder/webapp/WEB-INF/config/global.properties 
• /opt/pageseeder/webapp/WEB-INF/config/database.properties 
• /opt/pageseeder/webapp/WEB-INF/drivers/*.jar 

Once you have copied these files into the target system, you can use the following command:

$ /opt/pageseeder/bin/setup.sh --load-properties=/tmp/ps-import

You can use other options to override any of the properties, for example, to use the same properties but override the product key and website address, you can do:

$ /opt/pageseeder/bin/setup.sh \
  --load-properties=/tmp/ps-import \
  --website-address=ps.example.org \
  --product-key=xxxxxxxxxxxxxxxxxxxxx

Manual setup

Open up port 8282 to access the PageSeeder page:

# firewall-cmd --add-port=8282/tcp --zone=public

To access the setup page, go to:

http://ps.example.org:8282/ 

Once you no longer need access to port 8282

# firewall-cmd --remove-port=8282/tcp --zone=public

Set up a proxy

If a proxy like NGINX hasn’t been set up, follow instructions in Configuring a proxy for PageSeeder to handle SSL termination.

Troubleshooting

Check Java

To check that Java is installed:

$ which java

To check the Java version, PageSeeder 6 requires Java 11 or later

$ java -version

Missing driver

If you have the following error when trying to start PageSeeder

systemd[1]: Starting PageSeeder...
bash[13138]: PageSeeder has not been configured, missing database drivers
systemd[1]: pageseeder.service: Control process exited, code=exited, status=1/FAILURE
systemd[1]: pageseeder.service: Failed with result 'exit-code'.
systemd[1]: Failed to start PageSeeder.

The JDBC driver was not copied during the installation.

Make sure the driver is in your home directory

$ sudo /opt/pageseeder/bin/setup.sh --jdbc-driver=auto

If not you can specify the path directly:

$ sudo /opt/pageseeder/bin/setup.sh --jdbc-driver=/home/rocky/mysql-connector-j-8.0.33/mysql-connector-j-8.0.33.jar

Check that firewalld is running

To check whether firewalld is installed:

$ rpm -q firewalld

If firewalld is installed, this command will return the package name and version. If it is not, it will indicate that the package is not installed and you must do:

$ sudo dnf install firewalld

To check if the firewalld service is active and running, you can use systemctl:

$ systemctl status firewalld

To check the firewall configuration

$ sudo firewall-cmd --list-all
public (active)
  target: default
  icmp-block-inversion: no
  interfaces: eth0
  sources:
  services: cockpit dhcpv6-client http https ssh
  ports: 25/tcp
  protocols:
  forward: no
  masquerade: no
  forward-ports:
      port=25:proto=tcp:toport=2525:toaddr=
  source-ports:
  icmp-blocks:
  rich rules:

Sharing VM with Jetty

If the server is also running Jetty, serving a local web application, it is recommended to move PageSeeder to port 8443. This will require changes to the nginx configuration, and also allowing port 8443 through the firewall. Suggested nginx changes and firewalld commands are shown below.

server {
 listen       8443 ssl;
 server_name  [server host];

firewalld commands

firewall-cmd --permanent --zone=public --add-port=8443/tcp
firewall-cmd --reload

Tomcat shell script not running

If a Tomcat shell script such as startup.sh , shutdown.sh or catalina.sh does not run and return the error /bin/sh^M: bad interpreter: No such file or directory , it could be because it contains CR LF as line endings.

Use the following to fix the line terminators:

# sed -i -e 's/\r$//' /opt/pageseeder/tomcat/bin/catalina.sh

Script - database password not secure enough

If the database password you specified isn’t strong enough the overall script will fail but the pageseeder database will still be created, so if you strengthen the password and try to run the script again it will now fail because the pageseeder database already exists.

For new installs only - login to mysql and remove the pageseeder database before running the script

$ sudo mysql -u root -p

When logged into mysql

drop database pageseeder;

Exit and attempt to repeat configuration script.

Service troubleshooting

To check what the service link is pointing to:

$ readlink -f /etc/systemd/system/pageseeder.service

Service operations

To see the systemctl log

$ sudo journalctl -u pageseeder.service

To check the status of the service

$ sudo systemctl status pageseeder

To see all the settings for the service:

$ sudo systemctl cat pageseeder

To see edit the settings for the service:

$ sudo systemctl edit pageseeder

Sample pageseeder service override /etc/systemd/system/pageseeder.service.d/override.conf:

[Service]
Environment="CATALINA_OPTS=-Xmx1G -Djava.awt.headless=true -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/pageseeder"

If you make any change the configuration, you need to do the following:

$ sudo systemctl daemon-reload
$ sudo systemctl restart pageseeder

Change the configuration

You can change the PageSeeder system configuration at anytime with the setup.sh which has the following options:

# /opt/pageseeder/bin/setup.sh --help
Usage: /opt/pageseeder/bin/setup.sh
  -d --diagnostics         Print diagnostics
  -e --export=<dir>        Export the PageSeeder configuration to a folder
  -f --file=<file>         Load options from the specified file
  -h --help                Print this help
  -v --verbose             Print more details on the console
  General settings
  --java-options=<options> Set the Java options for PageSeeder
                           Default is "-Xmx1G"
  --jdbc-driver=<path>     Path to JDBC driver
                           Or 'auto' to find driver in user home
  --mail-port=<port>       Port for incoming emails [2525]
  --max-threads=<thread>   Maximum number of concurrent HTTP connections [200]
  --load-properties=<path> Path to directory containing global, database and group properties
                           Or 'auto' to find them in user home
  --no-restart             Do not restart the PageSeeder service
  --tomcat-port=<port>     Port used by tomcat [8282]
  License settings
  --website-address=<host> Hostname used for PageSeeder license
  --email-domain=<host>    Email domain
  --product-key=<key>      PageSeeder licence key
  SMTP Server
  --smtp-host=<host>       Host name of SMTP server for outgoing email
  --smtp-port=<port>       The port for the SMTP server
  --smtp-username=<user>   The username to access SMTP server
  --smtp-password=<pass>   The password to access SMTP server
  --smtp-ssl               If specified, connect to SMTP server using SSL
  --smtp-starttls          If specified, connect to SMTP server using TLS
 Database
   --update-database       If specified, update the database details using Setup API
   --db-type=<type>        Set to 'MySQL' or 'PostgreSQL'
   --db-host=<host>        Host name of database server
   --db-name=<name>        Name of database [pageseeder]
   --db-url=<url>          Custom URL to access the database
   --db-username=<user>    Username to access the PageSeeder database [pageseeder]
   --db-password=<pass>    Password to access the PageSeeder database
   --create-database       If specified, create the PageSeeder database, tables, and administrator
   --dba-username=<user>   Username of an administrator on the database server
   --dba-password=<pass>   Password of an administrator on the database server
   --admin-firstname=<firstname> The first name of the administrator
   --admin-surname=<surname>  The last name of the administrator
   --admin-email=<email>   The email address of the administrator
   --admin-username=<user> The username for the administrator
   --admin-password=<pass> The password for the administrator

For example to change the PageSeeder memory to 2 GB use the following (which will also restart PageSeeder automatically):

# /opt/pageseeder/bin/setup.sh --java-options=-Xmx2G

Script

To install PageSeeder, install Java first then execute the following as root.

#!/bin/bash

#MYSQL_DRIVER=8.0.36
#POSTGRESQL_DRIVER=42.7.4

# 1 Download driver (MySQL)
if [[ MYSQL_DRIVER ]]; then
  curl -LO http://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-${MYSQL_DRIVER}.tar.gz
  tar xzvf mysql-connector-j-${MYSQL_DRIVER}.tar.gz --wildcards '*.jar' 
fi

# 1 Download driver (PostGreSQL)
if [[ POSTGRESQL_DRIVER ]]; then
  curl -LO https://jdbc.postgresql.org/download/postgresql-${POSTGRESQL_DRIVER}.jar
fi

# 2. Install repo
sudo rpm -Uvh https://download.pageseeder.com/pub/rpm/pageseeder-repository-1.1-1.noarch.rpm

# 3. Install PageSeeder
dnf install pageseeder

# 4. Start the service
systemctl start pageseeder

# 5. Configure
/opt/pageseeder/bin/setup.sh -f options.conf