--- title: "New installation on el8/el9" source: https://dev.pageseeder.com/guide/installation/new_installation/new_installation_on_el8_el9.html description: "Guide for installing PageSeeder on Enterprise Linux 8/9 systems. Covers prerequisites, step-by-step installation via RPM repository, database driver setup, configuration options, troubleshooting, and service management." last_updated: 2026-08-14T15:51:59+10:00 tokens: ~3940 --- # New installation on el8/el9 Once the prerequisites described in [New installation](../new_installation.md) 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. | File / folder | Description | | --- | --- | | `/opt/pageseeder` | PageSeeder installation folder | | `/opt/pageseeder/bin/` | PageSeeder setup scripts (DO NOT MODIFY) | | `/opt/pageseeder/webapp/WEB-INF/config` | Contains your configuration files – not affected by upgrades | | `/opt/pageseeder/webapp/WEB-INF/drivers` | Folder where database drivers are stored – not affected by upgrades | | `/etc/systemd/system/pageseeder.service` | Definition of the PageSeeder services for systemd | ## 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 steps and 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](which_version_of_java.md)): ```shell # dnf -y install java-21-openjdk ``` If **firewalld** isn't installed, running and enabled, enter the following: ```shell # dnf install firewalld # systemctl start firewalld # systemctl enable firewalld ``` If you intend to run the database server, you need to install it before you install PageSeeder: - [Configuring MySQL](../mysql.md) - [Configuring PostgreSQL](../configuring_postgresql.md) Apply for a PageSeeder licence: - You can apply online to get a [90 day evaluation license](https://license.pageseeder.com/public/issue.html) for another domain. - To [license](../../../reference/glossary/license.md) 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 **to your `/home/[user]` directory** *(URLs and versions might have changed)*. If you intend to use MySQL: ```shell # wget https://downloads.mysql.com/archives/get/p/3/file/mysql-connector-j-8.4.0.tar.gz # tar xzvf mysql-connector-j-8.4.0.tar.gz --wildcards '*.jar' ``` If you intend to use PostgreSQL: ```shell $ 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)*: ```shell # rpm -Uvh https://download.pageseeder.com/pub/rpm/pageseeder-repository-1.3-1.el9.noarch.rpm ``` > **Note:** This lets you to install and update PageSeeder using `dnf`. ### Install PageSeeder Install PageSeeder with: ```shell # 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. ### Start the service ```shell # systemctl start pageseeder ``` ### Configure PageSeeder There are several options to configure PageSeeder - Use **option A** for manual setup using the setup wizard - Use **option B** for automated setup of a new installation - Use **option C** for a migration or a new installation based on an existing solution #### Manual setup Open up port 8282 to access the PageSeeder page: ```shell # firewall-cmd --add-port=8282/tcp --zone=public ``` To access the setup page, go to (you may need to use a private tab in your browser): [http://ps.example.org:8282/](http://ps.example.org:8282/)  Once you no longer need access to port 8282 ```shell # firewall-cmd --remove-port=8282/tcp --zone=public ``` #### 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. > **Note:** Some of these options include passwords, for security don’t enter the passwords on the command-line as they will appear in the history. You can either use an options file or save the passwords in variables, then use these in the command-line options. > **Note:** When specifying passwords be sure to use passwords secure enough to satisfy security requirements. If you’ve run a hardening process the password complexity requirements will be higher. Failing to set a password of high enough complexity can cause the script to fail midway, which will then require clean-up before the script will succeed, see troubleshooting for more information if you have that problem. Create an `options.conf` file and fill up with the values. Here is a typical options file to create: ```ini # 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)*: ```shell $ /opt/pageseeder/bin/setup.sh -f options.conf ``` #### Automated import If migrating from another server, on the original system export the `global.properties`, `database.properties`, and JDBC driver file (in `drivers` ) and save them into a directory as follows: ```shell $ /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: ```shell $ /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: ```shell $ /opt/pageseeder/bin/setup.sh \ --load-properties=/tmp/ps-import \ --website-address=ps.example.org \ --product-key=xxxxxxxxxxxxxxxxxxxxx ``` ### Set up a proxy If a proxy like NGINX hasn’t been set up, follow instructions in [Configuring a proxy](../configuring_a_proxy.md) for PageSeeder to handle SSL termination. ## Troubleshooting ### Check Java To check that Java is installed: ```shell $ which java ``` To check the Java version, PageSeeder 6 requires Java 11 or later ```shell $ 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 ```shell $ sudo /opt/pageseeder/bin/setup.sh --jdbc-driver=auto ``` If not you can specify the path directly: ```shell $ 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 ensure that the firewalld service is running and enabled use the following steps: ```shell $ sudo systemctl status firewalld ● firewalld.service - firewalld - dynamic firewall daemon  Loaded: loaded (/usr/lib/systemd/system/firewalld.service; disabled; vendor preset: enabled)  Active: inactive (dead) since Tue 2024-10-08 06:12:46 UTC; 20h ago ``` If firewalld is not installed, install it with: ```shell $ sudo dnf install firewalld ``` If the service status is **inactive**, start the service with: ```shell $ sudo systemctl start firewalld ``` If the service status is **disabled**, enable the service with: ```shell $ sudo systemctl enable firewalld ``` To check the firewall configuration: ```shell $ 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: ```shell # 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 ```shell $ 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: ```shell $ readlink -f /etc/systemd/system/pageseeder.service ``` ### Service operations To stop pageseeder. ```shell $ sudo systemctl stop pageseeder ``` > **Warning:** Stopping might take up to 2 minutes. **DO NOT** kill the process during this time as it could clear the caches. To see the systemctl log ```shell $ sudo journalctl -u pageseeder.service ``` To check the status of the service ```shell $ sudo systemctl status pageseeder ``` To see all the settings for the service: ```shell $ sudo systemctl cat pageseeder ``` To see edit the settings for the service: ```shell $ sudo systemctl edit pageseeder ``` Sample pageseeder service override `/etc/systemd/system/pageseeder.service.d/override.conf`: ```properties [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: ```shell $ 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: ```shell # /opt/pageseeder/bin/setup.sh --help Usage: /opt/pageseeder/bin/setup.sh -d --diagnostics Print diagnostics -e --export= Export the PageSeeder configuration to a folder -f --file= Load options from the specified file -h --help Print this help -v --verbose Print more details on the console General settings --java-options= Set the Java options for PageSeeder Default is "-Xmx1G" --jdbc-driver= Path to JDBC driver Or 'auto' to find driver in user home --mail-port= Port for incoming emails [2525] --max-threads= Maximum number of concurrent HTTP connections [200] --load-properties= 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 used by tomcat [8282] License settings --website-address= Hostname used for PageSeeder license --email-domain= Email domain --product-key= PageSeeder licence key SMTP Server --smtp-host= Host name of SMTP server for outgoing email --smtp-port= The port for the SMTP server --smtp-username= The username to access SMTP server --smtp-password= 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= Set to 'MySQL' or 'PostgreSQL' --db-host= Host name of database server --db-name= Name of database [pageseeder] --db-url= Custom URL to access the database --db-username= Username to access the PageSeeder database [pageseeder] --db-password= Password to access the PageSeeder database --create-database If specified, create the PageSeeder database, tables, and administrator --dba-username= Username of an administrator on the database server --dba-password= Password of an administrator on the database server --admin-firstname= The first name of the administrator --admin-surname= The last name of the administrator --admin-email= The email address of the administrator --admin-username= The username for the administrator --admin-password= The password for the administrator ``` For example to change the PageSeeder memory to 2 GB use the following (which will also restart PageSeeder automatically): ```shell # /opt/pageseeder/bin/setup.sh --java-options=-Xmx2G ``` ## Script To install PageSeeder, install Java first then execute the following as **root**. ```bash #!/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 ```