Difference between revisions of "Installing EPrints on RHEL/Fedora/CentOS"

From EPrints Documentation
Jump to: navigation, search
m (Installing RPM locally)
m (Added an anchor link to the Getting Started and Apache part of Installing EPrints 3.4.x from Source to make mentioning in an EP Tech article easier. May need a dedicated subheading in due course too.)
 
(25 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
==Requirements==
 
==Requirements==
* RedHat Enterprise (RHEL) / CentOS 7 or 8 (or Fedora 25+).
+
* RedHat Enterprise (RHEL) / CentOS 7, 8 or 9 (or Fedora 25+).
 
* Pre-install MySQL server and client and make sure the former is enabled and running.
 
* Pre-install MySQL server and client and make sure the former is enabled and running.
 
** RHEL / Fedora:
 
** RHEL / Fedora:
 
  yum install mysql-server mysql
 
  yum install mysql-server mysql
  systemctl enable mysql
+
  systemctl enable --now mysqld
systemctl start mysql
+
 
** CentOS:
+
** CentOS / Rocky Linux:
 
  yum install mariadb-server mariadb
 
  yum install mariadb-server mariadb
  systemctl enable mariadb
+
  systemctl enable --now mariadb
systemctl start mariadb
 
 
 
== Installing from EPrints RPM ==
 
 
 
=== Installing from rpm.eprints.org ===
 
'''Please note that rpm.eprints.org is no longer fully supported and packages are no longer signed.  It is planned to start signing packages again in the future but there have been some issues with the signing keys.'''
 
 
 
* As root, using yum (or dnf in RHEL/CentOS 8+ and more recent Fedora versions) install ''epel-release'' package so ''eprints'' RPM dependencies can be met from the EPEL repository where necessary:
 
yum install epel-release
 
dnf install epel-release
 
 
 
* As root, edit /etc/yum.repos.d/eprints.repo and add the following (If you want to install EPrints 3.3 rather than EPrints 3.4 change the baseurl to ''http://rpm.eprints.org/eprints3''):
 
[eprints_3_4]
 
name=EPrints Repository Software - $basearch
 
baseurl=http://rpm.eprints.org/eprints3.4
 
enabled=1
 
gpgcheck=0
 
 
 
* As root, now run one of the following commands to download the cache for this new package repositories.  You may be prompted to accept the GPG key for the EPEL repository:
 
yum makecache
 
dnf makecache
 
 
 
* Finally, install EPrints using yum (or dnf):
 
yum install eprints
 
dnf install eprints
 
 
 
=== Installing RPM locally ===
 
* Download latest RPM for EPrints 3.3 or 3.4 from http://files.eprints.org/
 
 
 
* Then install EPrints using yum (or dnf in RHEL/CentOS 8+ and more recent Fedora versions) substituting for the filename of the file you downloaded from  https://files.eprints.org
 
yum install eprints-3.3.16-1.el7.rpm
 
dnf install eprints-3.4.4-1.el7.pm
 
 
 
=== Installing publications flavour ===
 
EPrints 3.4 RPMs only come with the in-built 'zero' flavour and not the typical publications flavour.  Before trying to set up you archive you will need to (as the eprints user) download the latest publications flavour tarball from https://files.eprints.org/ and unpack it into /usr/share/eprints/:
 
wget https://files.eprints.org/2551/8/eprints-3.4.3-flavours.tar.gz
 
tar -xzvf eprints-3.4.3-flavours.tar.gz -C /usr/share/eprints/
 
mv /usr/share/eprints/eprints-3.4.3/flavours /usr/share/eprints/
 
rmdir /usr/share/eprints/eprints-3.4.3/
 
Before trying to create a publications flavour archive, you will need to install (as the root user) the ''TeX::Encode'' module or you will see error messages regarding a missing dependency for the BibTeX import and export plugins. (You may need to first install ''cpan'' with YUM).
 
yum install cpan
 
cpan TeX::Encode
 
  
 
== Installing EPrints 3.4.x from Source ==
 
== Installing EPrints 3.4.x from Source ==
'''N.B. Installing from source is generally discouraged particularly for production repositories.  However, if want to develop the EPrints code or a plugin or Bazaar package it may be useful to install from source, ideally from [https://github.com/eprints/eprints3.4 EPrints Core Git repository].'''
+
'''Ideally you will install from source from [https://github.com/eprints/eprints3.4 EPrints Core Git repository]. Installing from source is now the preferred way to install production repositories, having previously proved to be a useful installation method for those wishing to develop EPrints code or a plugin or Bazaar package too.'''
  
 
First, install the EPEL YUM package repository and run yum repolist to ensure the GPG key is installed:
 
First, install the EPEL YUM package repository and run yum repolist to ensure the GPG key is installed:
Line 64: Line 22:
 
Now, install all the dependencies that would be installed through the eprints RPM.
 
Now, install all the dependencies that would be installed through the eprints RPM.
  
  yum install libxml2 libxslt httpd mod_perl perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL perl-Time-HiRes \
+
  yum install libxml2 libxslt httpd mod_perl perl-Apache-DBI perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL \
    perl-CGI perl-Digest-MD5 perl-Digest-SHA perl-JSON perl-XML-LibXML perl-XML-LibXSLT perl-XML-SAX \
+
    perl-Time-HiRes perl-CGI perl-Digest-MD5 perl-Digest-SHA perl-Digest-SHA1 perl-JSON perl-XML-LibXML \
    perl-MIME-Lite perl-Text-Unidecode perl-JSON perl-Unicode-Collate perl-Pod-LaTeX perl-LWP-Protocol-https \
+
    perl-XML-LibXSLT perl-XML-SAX perl-MIME-Lite perl-Text-Unidecode perl-JSON perl-Unicode-Collate \
    perl-IO-String tetex-latex wget gzip tar ImageMagick elinks poppler-utils chkconfig unzip cpan
+
    perl-Pod-LaTeX perl-LWP-Protocol-https perl-IO-String tetex-latex wget gzip tar ImageMagick elinks \
 +
    poppler-utils chkconfig unzip cpan python3-html2text
  
 
Next, create the eprints user
 
Next, create the eprints user
Line 76: Line 35:
  
 
  yum install git
 
  yum install git
  mkdir /opt/eprints3/
+
  mkdir /opt/eprints3
  chown eprints:eprints /opt/eprints3/
+
  chown eprints:eprints /opt/eprints3
  chmod 2775 /opt/eprints3/
+
  chmod 2775 /opt/eprints3
 
  su eprints
 
  su eprints
 
  git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
 
  git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
  git checkout tags/v3.4.4
+
cd /opt/eprints3/
 +
  git checkout tags/v3.4.5
  
Next, as the eprints user copy /opt/eprints3/perl_lib/EPrints/SystemSettings.pm.tmpl to /opt/eprints3/perl_lib/Eprints/SystemSettings.pm
+
Next, as the eprints user copy /opt/eprints3/perl_lib/EPrints/SystemSettings.pm.tmpl to /opt/eprints3/perl_lib/EPrints/SystemSettings.pm
  
EPrints is now fully installed at /opt/eprints3. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.
+
<span id="getting_started_and_apache">EPrints</span> is now fully installed at /opt/eprints3. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.
  
 
Now update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in /etc/httpd/conf/httpd.conf:
 
Now update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in /etc/httpd/conf/httpd.conf:
Line 105: Line 65:
  
 
== Non-critical Dependencies ==
 
== Non-critical Dependencies ==
Some of EPrints non-core functionality may not work out of the box as these dependencies are not included as part of the RPM.  Here is a list of known additional packages (and the YUM repositories in which they can be found) or CPAN modules than can be installed.  The latter should be installed using the ''cpan'' command as the root user.
+
Some of EPrints non-core functionality may not work out of the box as these dependencies are not included as part of the installation process.  Here is a list of known additional packages (and the YUM repositories in which they can be found) or CPAN modules than can be installed.  The latter should be installed using the ''cpan'' command as the root user.
 
   
 
   
 
* '''perl-Geo-IP (epel)''' - Allows IRstats2 to determine the location of views/downloads for publications.]
 
* '''perl-Geo-IP (epel)''' - Allows IRstats2 to determine the location of views/downloads for publications.]
Line 117: Line 77:
  
 
Configure eprints per [[Getting_Started_with_EPrints_3]].
 
Configure eprints per [[Getting_Started_with_EPrints_3]].
 +
 +
== Installing using RPM package ==
 +
As of EPrints 3.4.5 RPM (.rpm) packages will no longer be produced.  Due to the complexity of the installation process there are a number of inherent problems with installing using a RPM package. As new operating systems (e.g. RHEL, Fedora, CentOS, Rocky Linux, etc.) are released the available packages have changed.  This often leads to packages upon which that EPrints depends ceasing to be available.  This makes it very difficult or impossible to install the RPM package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional RPM repositories or using CPAN).  However, the main concern of installation the RPM package, particularly through EPrints' RPM repository, is that it can lead to EPrints being upgraded automatically to a new version.  Upgrading EPrints using a RPM package is likely to lead to EPrints producing errors, as configuration changes are often required as part of the upgrade process.  Automating these changes within the RPM package would be all but impossible due to EPrints' high level of customisability.
  
 
== Operating System Version Specific Requirements ==
 
== Operating System Version Specific Requirements ==
Line 125: Line 88:
 
=== RHEL / CentOS / Rocky 8 ===
 
=== RHEL / CentOS / Rocky 8 ===
 
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 8}}
 
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 8}}
 +
 +
=== RHEL / CentOS / Rocky 9 ===
 +
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 9}}
  
 
== Troubleshooting ==
 
== Troubleshooting ==
* If setup in successful but then you can access EPrints through your web browser this is often due to firewalld being enabled by default on recent versions of RHEL, Fedora and CentOS.  If firewalld is running either disable it (<tt>systemctl disable --now firewalld</tt>) or [https://docs.rackspace.com/support/how-to/allow-web-traffic-in-a-firewalld-software-firewall/ configure it to allow HTTP/HTTPS traffic].
+
* If setup is successful but then you cannot access EPrints through your web browser this is often due to firewalld being enabled by default on recent versions of RHEL, Fedora and CentOS.  If firewalld is running either disable it (<tt>systemctl disable --now firewalld</tt>) or [https://docs.rackspace.com/support/how-to/allow-web-traffic-in-a-firewalld-software-firewall/ configure it to allow HTTP/HTTPS traffic].
 
* If you are having problems uploading files or similar functional issues, this may be due to SELinux being enabled. [[EPrints and SELinux|See advice for enabling SELinux with EPrints]].
 
* If you are having problems uploading files or similar functional issues, this may be due to SELinux being enabled. [[EPrints and SELinux|See advice for enabling SELinux with EPrints]].
 +
* If you are having trouble getting additional subdomains beyond username.eprints-hosting.org working, then it could be you need wildcards enabled on the DNS records to facilitate the likes of somethingcoolhere.username.eprints-hosting.org urls.

Latest revision as of 14:11, 11 December 2023


Requirements

  • RedHat Enterprise (RHEL) / CentOS 7, 8 or 9 (or Fedora 25+).
  • Pre-install MySQL server and client and make sure the former is enabled and running.
    • RHEL / Fedora:
yum install mysql-server mysql
systemctl enable --now mysqld
    • CentOS / Rocky Linux:
yum install mariadb-server mariadb
systemctl enable --now mariadb

Installing EPrints 3.4.x from Source

Ideally you will install from source from EPrints Core Git repository. Installing from source is now the preferred way to install production repositories, having previously proved to be a useful installation method for those wishing to develop EPrints code or a plugin or Bazaar package too.

First, install the EPEL YUM package repository and run yum repolist to ensure the GPG key is installed:

yum install epel-release
yum repolist

Now, install all the dependencies that would be installed through the eprints RPM.

yum install libxml2 libxslt httpd mod_perl perl-Apache-DBI perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL \
    perl-Time-HiRes perl-CGI perl-Digest-MD5 perl-Digest-SHA perl-Digest-SHA1 perl-JSON perl-XML-LibXML \
    perl-XML-LibXSLT perl-XML-SAX perl-MIME-Lite perl-Text-Unidecode perl-JSON perl-Unicode-Collate \
    perl-Pod-LaTeX perl-LWP-Protocol-https perl-IO-String tetex-latex wget gzip tar ImageMagick elinks \
    poppler-utils chkconfig unzip cpan python3-html2text

Next, create the eprints user

adduser eprints

Next, clone the Git repository from GitHub to /opt/ and set the eprints user as the owner. It is probably best to checkout the latest release rather than using HEAD, which may have known issues:

yum install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.5

Next, as the eprints user copy /opt/eprints3/perl_lib/EPrints/SystemSettings.pm.tmpl to /opt/eprints3/perl_lib/EPrints/SystemSettings.pm

EPrints is now fully installed at /opt/eprints3. However, you will not yet have a running archive. Follow the Getting Started with EPrints 3 instructions to set this up.

Now update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in /etc/httpd/conf/httpd.conf:

User  eprints
Group eprints

Now add the file /etc/httpd/conf.d/eprints.conf with the following line:

Include /opt/eprints3/cfg/apache.conf

There is a good chance your operating system will have SELinux enabled. If so, follow the instructions under Troubleshooting for how to let EPrints do what it needs to do through SELinux.

Finally, restart Apache:

 service httpd restart

You should now be able to access your vanilla repository at the hostname you specified when running epadmin create from the Getting Started with EPrints 3 instructions. You should then login as the admin user you created during this process and turn on the indexer. This can be done by clicking on the Admin link under the Logged in menu, then clicking on the System Tools tab and finally the Start Indexer button.

Non-critical Dependencies

Some of EPrints non-core functionality may not work out of the box as these dependencies are not included as part of the installation process. Here is a list of known additional packages (and the YUM repositories in which they can be found) or CPAN modules than can be installed. The latter should be installed using the cpan command as the root user.

  • perl-Geo-IP (epel) - Allows IRstats2 to determine the location of views/downloads for publications.]
  • perl-Spreadsheet-WriteExcel (epel) - To allow Multiline Excel export.
  • CPAN module Text::Refer - Required for EndNote import.
  • CPAN module TeX::Encode - Required for BibTex export needed for publications flavour.
  • perl-Image-ExifTool (epel) - Sometimes needed to support generation of thumbnails for uploaded documents/images.
  • perl-LWP-Protocol-https (base) - Needed by DataCite plugin to register repository DOIs.

Next steps

Configure eprints per Getting_Started_with_EPrints_3.

Installing using RPM package

As of EPrints 3.4.5 RPM (.rpm) packages will no longer be produced. Due to the complexity of the installation process there are a number of inherent problems with installing using a RPM package. As new operating systems (e.g. RHEL, Fedora, CentOS, Rocky Linux, etc.) are released the available packages have changed. This often leads to packages upon which that EPrints depends ceasing to be available. This makes it very difficult or impossible to install the RPM package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional RPM repositories or using CPAN). However, the main concern of installation the RPM package, particularly through EPrints' RPM repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a RPM package is likely to lead to EPrints producing errors, as configuration changes are often required as part of the upgrade process. Automating these changes within the RPM package would be all but impossible due to EPrints' high level of customisability.

Operating System Version Specific Requirements

RHEL / CentOS 7

No significant issues.

RHEL / CentOS / Rocky 8

elinks package is no longer available

The RPM package elinks is no longer available in RHEL / CentOS / Rocky 8 even with EPEL package repository. elinks is only needed if are intending to upload web pages or XML files and these need to be indexed by EPrints, so if installing from source use the following DNF command line:

dnf install libxml2 libxslt httpd mod_perl perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL perl-Time-HiRes \
   perl-CGI perl-Digest-MD5 perl-Digest-SHA perl-JSON perl-XML-LibXML perl-XML-LibXSLT perl-XML-SAX \
   perl-MIME-Lite perl-Text-Unidecode perl-JSON perl-Unicode-Collate perl-Pod-LaTeX tetex-latex wget \
   gzip tar ImageMagick poppler-utils chkconfig unzip cpan

Alternatively, for RHEL 8 you can enable the codeready-builder repository, which still has elinks available:

subscription-manager repos --enable "codeready-builder-for-rhel-8-$(arch)-rpms"

If you are running CentOS 8 (or Rocky 8) you can similarly enable the powertools repository:

dnf config-manager --set-enabled powertools

perl-IO-String package is no longer available

The RPM package perl-IO-String is no longer available in RHEL / CentOS / Rocky 8 even with EPEL package repository. You can enable the codeready-builder repository, which still has perl-IO-String available:

subscription-manager repos --enable "codeready-builder-for-rhel-8-$(arch)-rpms"

If you are running CentOS 8 (or Rocky 8) you can similarly enable the powertools repository:

dnf config-manager --set-enabled powertools

Sub-dependency packages perl-MIME-Types and perl-Digest-SHA1 are no longer available

perl-MIME-Lite package requires perl-MIME-Types package and perl-Apache-DBI requires perl-Digest-SHA1 package neither of which available on RHEL / CentOS / Rocky 8, even with EPEL repository enabled. You can enable the codeready-builder repository, which still has these packahes available:

subscription-manager repos --enable "codeready-builder-for-rhel-8-$(arch)-rpms"

If you are running CentOS 8 (or Rocky 8) you can similarly enable the powertools repository:

dnf config-manager --set-enabled powertools

Compatibility issues with XML::LibXSLT

Installing XML::LibXSLT either through the perl-XML-LibXSLT RPM or CPAN causes httpd to generate a segmentation fault when you try to start it. The most straightfarward solution to this is to run httpd in mpm-prefork rather than mpm-event mode. This can be acheived by editing /etc/httpd/conf.modules.d/00-mpm.conf and commenting out the following line:

LoadModule mpm_event_module modules/mod_mpm_event.so

and uncommenting the mpm-prefork line:

LoadModule mpm_prefork_module modules/mod_mpm_prefork.so

The alternative solution is to make sure that XML::LibXSLT is not installed through the perl-XML-LibXSLT RPM or CPAN. EPrints will still run without this but you will not be able to use XSLT-based import plugins. Unless you have installed any additional import plugins, the only ones affected are Atom XML and OpenXML Bibliography.

RHEL / CentOS / Rocky 9

elinks package is no longer available

The RPM package elinks is no longer available in RHEL / CentOS / Rocky 9 even with EPEL package repository. elinks is only needed if are intending to upload web pages or XML files and these need to be indexed by EPrints, so if installing from source use the following DNF command line:

dnf install libxml2 libxslt httpd mod_perl perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL perl-Time-HiRes \
   perl-CGI perl-Digest-MD5 perl-Digest-SHA perl-JSON perl-XML-LibXML perl-XML-LibXSLT perl-XML-SAX \
   perl-MIME-Lite perl-Text-Unidecode perl-JSON perl-Unicode-Collate tetex-latex wget gzip tar \
   ImageMagick poppler-utils chkconfig unzip cpan python3-html2text

In future versions of EPrints (3.4.5+) EPrints will be switching to use html2text rather than elinks. changeset shows how the places where elinks is used can be changed to switch over to using html2text. To make use of this you will need to add python3-html2text to the DNF command above.

perl-IO-String package is no longer available

The RPM package perl-IO-String is no longer available in RHEL / CentOS / Rocky 9 even with EPEL package repository. You can enable the Code Ready Builder repository, which still has perl-IO-String available:

subscription-manager repos --enable "codeready-builder-for-rhel-9-$(arch)-rpms"

If you are running CentOS 9 (or Rocky 9) you can similarly enable the crb repository:

dnf config-manager --set-enabled crb

Then install perl-IO-String:

dnf install perl-IO-String

Sub-dependency packages perl-MIME-Types and perl-Digest-SHA1 are no longer available

perl-MIME-Lite package requires perl-MIME-Types package and perl-Apache-DBI requires perl-Digest-SHA1 package neither of which available on RHEL / CentOS / Rocky 9, even with EPEL repository enabled. You can enable the Code Ready Builder repository, which still has these packages available:

subscription-manager repos --enable "codeready-builder-for-rhel-9-$(arch)-rpms"

If you are running CentOS 9 (or Rocky 9) you can similarly enable the crb repository:

dnf config-manager --set-enabled crb

Then install perl-MIME-Types and perl-Digest-SHA1:

dnf install perl-MIME-Types perl-Digest-SHA1

perl-Apache-DBI and Pod::LaTeX packages is no longer available

The RPM packages perl-Apache-DBI are no longer available in RHEL / CentOS / Rocky 9 even with EPEL or Code Ready Builder package repository. You can install this using CPAN instead:

cpan Apache::DBI
cpan Pod::LaTeX

Compatibility issues with XML::LibXSLT

Installing XML::LibXSLT either through the perl-XML-LibXSLT RPM or CPAN causes httpd to generate a segmentation fault and core dump when you try to start it. The most straightfarward solution to this is to run httpd in mpm-prefork rather than mpm-event mode. This can be acheived by editing /etc/httpd/conf.modules.d/00-mpm.conf and commenting out the following line:

LoadModule mpm_event_module modules/mod_mpm_event.so

and uncommenting the mpm-prefork line:

LoadModule mpm_prefork_module modules/mod_mpm_prefork.so

The alternative solution is to make sure that XML::LibXSLT is not installed through the perl-XML-LibXSLT RPM or CPAN. EPrints will still run without this but you will not be able to use XSLT-based import plugins. Unless you have installed any additional import plugins, the only ones affected are Atom XML and OpenXML Bibliography.

MySQL root user cannot be used

On RHEL/Centos/Rocky Linux 9 rather than prompting you to set a password for MySQL server when installing this as a dependency, it just installs it without. However, this means on the root user can login to MySQL to add a database. As "epadmin create" runs at the eprints user, this will not be able to create a database for EPrints. To get round this as the root user connect to MySQL (just type "mysql" at the command line) and type the following two commands. You will want to set your own password (i.e. not 'changeme') , you may also want to restrict which databases the eprints user has control over. If you know the "Archive ID" you are going to use.

CREATE USER 'eprints'@'localhost' IDENTIFIED by 'changeme';
GRANT ALL PRIVILEGES ON *.* TO 'eprints'@'localhost' WITH GRANT OPTION;

Troubleshooting

  • If setup is successful but then you cannot access EPrints through your web browser this is often due to firewalld being enabled by default on recent versions of RHEL, Fedora and CentOS. If firewalld is running either disable it (systemctl disable --now firewalld) or configure it to allow HTTP/HTTPS traffic.
  • If you are having problems uploading files or similar functional issues, this may be due to SELinux being enabled. See advice for enabling SELinux with EPrints.
  • If you are having trouble getting additional subdomains beyond username.eprints-hosting.org working, then it could be you need wildcards enabled on the DNS records to facilitate the likes of somethingcoolhere.username.eprints-hosting.org urls.