Installing EPrints on RHEL/Fedora/CentOS

Requirements

• Red Hat Enterprise (RHEL) / CentOS / Rocky Linux 8 or 9. (EPrints can be installed on RHEL / CentOS / Rocky Linux 10 but there are currently a number of issues, some which should be resolved in later version of these Linux OSs).

Prerequisites

• Pre-install and enable the EPEL DNF repository.

  • dnf install epel-release

• Pre-install and enable the CodeReady Builder DNF repository.
  • RHEL

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

  • CentOS Stream / Rocky Linux 8

    dnf config-manager --set-enabled powertools

  • CentOS Stream / Rocky Linux 9 and 10

    dnf config-manager --set-enabled crb

• Pre-install MySQL server and client and make sure the former is enabled and running.
  • RHEL / Fedora:

    dnf install mysql-server mysql mysql-devel
 systemctl enable --now mysqld

  • CentOS / Rocky Linux:

    dnf install mariadb-server mariadb mariadb-devel
 systemctl enable --now mariadb

• From the MySQL command prompt, pre-configure an eprints user with password for MariaDB/MySQL, which can be used as the Database super user when creating the database for an archive. (Be sure to change the password from "changeme"):

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

• As root, from a command prompt add the eprints user:

  adduser eprints

Dependencies

The following RPMs need to be installed using the dnf command:

dnf 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-LWP-Protocol-https perl-IO-String tetex-latex wget gzip tar ImageMagick poppler-utils \
    chkconfig unzip cpan python3-html2text expat-devel libxslt-devel

N.B. If you are running RHEL / CentOS / Rocky Linux 10, perl-Apache-DBI is no longer available and will need to be installed with CPAN and python3-html2text will not be available until RHEL / CentOS / Rocky Linux 10.1. You should exclude these when running the dnf command above. (See Operating System Version Specific Requirements for RHEL / CentOS / Rocky Linux 10 below for more details).

Installing EPrints 3.4.6 from Source

Ideally you will install from source from EPrints Core Git repository, which includes the core codebase and the publications flavour. However, you may choose to download tarballs of the EPrints core codebase and publications flavour from files.eprints.org as an alternative means of installation.

From GitHub

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:

dnf 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.6

From files.eprints.org

Download and unpack the core codebase tarball for files.eprints.org.

cd /tmp/
wget https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz
tar -xzvf eprints-3.4.6.tar.gz

Then move in the source code into place:

mv eprints-3.4.6 /opt/eprints3
chmod 2775 /opt/eprints3
chown -R eprints:eprints /opt/eprints3

If you want a publications flavoured repository, then you will also need to download, unpack and move that into the appropriate location:

wget https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6/flavours/pub_lib /opt/eprints3/flavours
chmod -R g+w /opt/eprints3/flavours/pub_lib
chown -R eprints:eprints /opt/eprints3/flavours/pub_lib

Configuration

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.

Post-configuration

Add the eprints user to the apache group and vice-versa.

usermod -aG apache eprints
usermod -aG eprints apache

Finally, restart Apache:

 service httpd restart

SELinux

There is a fair chance your operating system will have SELinux enabled. If so, follow the advice at EPrints and SELinux for how to let EPrints do what it needs to do through SELinux. Otherwise, you could disable SELinux with the following:

setenforce 0

However, that will only disable it until the next reboot. You should also edit /etc/selinux/config and make sure the SELINUX=enforcing is set to:

SELINUX=disabled

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 DNF 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. (RHEL/CentOS/Rocky Linux 8 only)
• perl-GeoIP2 (@System and epel) - Allows IRstats2 to determine the location of views/downloads for publications. (RHEL/CentOS/Rocky Linux 9+)
• 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.

Operating System Version Specific Requirements

RHEL / CentOS / Rocky 8

No known issues if running at least EPrints 3.4.6.

RHEL / CentOS / Rocky 9

No known issues if running at least EPrints 3.4.6.

RHEL / CentOS / Rocky 10

No other known issues beyond those below if running at least EPrints 3.4.6.

mod_perl cannot handle dir_perms parameter

By default EPrints is configures its dir_perms parameter to 02775 in perl_lib/EPrints/SystemSettings.pm and lib/syscfg.d/core.pl. This is used when creating a new directory with EPrints::System::mkdir, which call CORE::mkdir. Previously this core Perl function has ignored the mask for the setuid/setgid/sticky bit so it did not matter^ if dir_perms was 02775 or 0775 but the version of mod_perl used on RHEL-based Linux 10 now gets confused by this and will fail to create directory. To fix this you will need to modify lib/syscfg.d/core.pl and set $c->{dir_perms} as follows:

$c->{dir_perms} = '0775';

In addition, to make sure that the setgid bit gets set the same as it would before, it is advised you make sure all the sub-directories in your archive have the setgid bit set:

find EPRINTS_PATH/archives/ARCHIVE_ID -type d -exec chmod g+s {} \;

Technically, it should not be necessary to do this to all directories, it might be sufficient to do this only to the html and documents directories, as well as their sub-directories but there should not be any problem updating all the archive's directories.

^This is why EPrints::System::mkdir would subsequently called CORE::chmod to update setuid/setgid/sticky bits on the newly created directories.

perl-Apache-DBI not available through DNF package manager

RHEL / CentOS / Rocky 10 does not include perl-Apache-DBI in their DNF package managers. Therefore, you will need to install afterwards using cpan:

cpan Apache::DBI

python3-html2text not available in EPEL until 10.1

The EPEL DNF repository does not include python3-html2text until RHEL / CentOS / Rocky 10.1 expected sometime in November 2025. If you need to upload HTML files and have them indexed in your EPrints repository it is advised you install to an early version or RHEL or one of its derivatives for now until a suitable solution to this issue can be found.

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 running a version of EPrints below 3.4.6 you cannot run Apache in MPM event mode and you need to use MPM prefork instead. This is due to Perl's XML::LibXSLT being initiated at the wrong time leading earlier version of EPrints to cause Apache (httpd) to segfault when started. If you are running an earlier version and want to run Apache in MPM event mode, you can uninstall XML::LibXSLT either as the RPM perl-XML-LibXSLT or possible from CPAN using cpanm --uninstall XML::LibXSLT.
• 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.