EPrints Documentation - User contributions [en-gb]

Installing EPrints on RHEL/Fedora/CentOS

2023-12-11T14:11:15Z

Ajm: 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.

[[Category:Installation]]

==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 [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:

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

<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:

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 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 8}}

=== RHEL / CentOS / Rocky 9 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 9}}

== 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 (<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 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.

Extension Packages

2023-11-08T15:27:11Z

Ajm: Typo correction - reposityory -> repository

[[Category:Contribute]]
[[Category:Plugins]]
An extension package is a .tgz file containing multiple files which adds a suite of functionality when unpacked in the /opt/eprint3/archives/ARCHIVE_ID/ directory.

An extension can be as simple as a plugin plus a css file or add a whole exciting suite of new features.

Things you might want to put into an eprints extension package:

* Plugins: archives/ARCHIVE_ID/cfg/plugins/EPrints/Plugin/...
* Themes: lib/themes/...
* scripts: archives/ARCHIVE_ID/bin/...
* CGI scripts: archives/ARCHIVE_ID/cgi/...
* autocompletion scripts: archives/ARCHIVE_ID/cgi/users/lookup/...
* phrase files for use by plugins or scripts: archives/ARCHIVE_ID/cfg/lang/.../phrases/...
* images, icons, javascript and css files to support your plugins or scripts: archives/ARCHIVE_ID/cfg/static/...

Other things you might want to include are...
* configuration files
* repository specific phrase files
* autocompletion data files

The handy thing is that plugins are autoloaded, .xml files in the phrases directory are autoloaded and .pl files in the archive cfg.d are autoloaded. So if you want to give your plugin some config options, you could just give a .pl file to copy into the cfg.d/ dir looking something like.

$c->{extension}->{my_cool_extension}->{option_1} = 1;
$c->{extension}->{my_cool_extension}->{keep_alive} = "always";

And access it in your code like:

$option_1 = $plugin->{repository}->conf( "extension", "my_cool_extension", "option_1" )

etc.

You could use a shorter path in the $c datastructure, but try and make sure it's distinct to your extension so clashes don't happen.

$c->{PreviewPlus_alignment} = "vertical";

and then

$option_1 = $plugin->{repository}->conf( "PreviewPlus_alignment" );

Installing EPrints on Debian/Ubuntu

2023-10-14T11:20:21Z

Ajm: Changed heading types.

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 18.04 LTS, 20.04 LTS or 22.04 LTS and (non-LTS versions not recommended)
* Debian 9 (Stretch), 10 (Buster) or Debian 11 (Bullseye) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints:

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-base-bin psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client

Next, create the eprints user

adduser eprints

Now, update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in <code>/etc/apache2/envvars</code>:

export APACHE_RUN_USER=eprints
export APACHE_RUN_GROUP=eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt 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
git checkout tags/v3.4.5

==== EPrints 3.3.x for GitHub ====

apt install git
mkdir /opt/eprints3/
chown eprints:eprints /opt/eprints3/
chmod 2775 /opt/eprints3/
su eprints
git clone https://github.com/eprints/eprints.git /opt/eprints3
git checkout tags/v3.3.16

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/2789/7/eprints-3.4.5.tar.gz
tar -xzvf eprints-3.4.5.tar.gz

Then put in the source code in place:

mv eprints-3.4.5 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) 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 Deb package. As new operating systems (e.g. Debian and Ubuntu) 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 Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian 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 Debian package would be all but impossible due to EPrints' high level of customisability.

=== Installing publications flavour ===
EPrints 3.4 DEBs 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/

== Configuration ==
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 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.

=== Useful commands for source development and testing ===
The following commands may be useful for those developing or testing EPrints but are not necessary for installing EPrints.
==== Install EPrints build dependencies ====
apt-get build-dep eprints
==== Get EPrints source ====
apt-get source eprints
==== Rebuilding ====
To change the way the eprints builds you can edit the debian/rules file (the only line you will want is the configure one). Once done you can then type <code>dpkg-buildpackage -rfakeroot</code> from the root dir of the extracted tarball.

This will build you a .deb in the directory above your current location, which can then be installed usinging dpkg:
dpkg -i ../eprints-X.X.X_all.deb

Alternatively you can configure and install it yourself (a non debian specific version) by configuring manually and then running install.pl:
$ ./configure --with-smtp-server=smtp.yourdomain
$ sudo ./install.pl

== Operating System Version Specific Requirements ==

=== Ubuntu 18.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 18.04}}

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2023-10-14T11:19:26Z

Ajm: /* Installing from Debian package */ Changed heading type.

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 18.04 LTS, 20.04 LTS or 22.04 LTS and (non-LTS versions not recommended)
* Debian 9 (Stretch), 10 (Buster) or Debian 11 (Bullseye) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints:

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-base-bin psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client

Next, create the eprints user

adduser eprints

Now, update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in <code>/etc/apache2/envvars</code>:

export APACHE_RUN_USER=eprints
export APACHE_RUN_GROUP=eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt 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
git checkout tags/v3.4.5

==== EPrints 3.3.x for GitHub ====

apt install git
mkdir /opt/eprints3/
chown eprints:eprints /opt/eprints3/
chmod 2775 /opt/eprints3/
su eprints
git clone https://github.com/eprints/eprints.git /opt/eprints3
git checkout tags/v3.3.16

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/2789/7/eprints-3.4.5.tar.gz
tar -xzvf eprints-3.4.5.tar.gz

Then put in the source code in place:

mv eprints-3.4.5 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

=== Installing from Debian package ===
As of EPrints 3.4.5 Debian (.deb) 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 Deb package. As new operating systems (e.g. Debian and Ubuntu) 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 Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian 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 Debian package would be all but impossible due to EPrints' high level of customisability.

=== Installing publications flavour ===
EPrints 3.4 DEBs 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/

=== Configuration ===
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 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.

=== Useful commands for source development and testing ===
The following commands may be useful for those developing or testing EPrints but are not necessary for installing EPrints.
==== Install EPrints build dependencies ====
apt-get build-dep eprints
==== Get EPrints source ====
apt-get source eprints
==== Rebuilding ====
To change the way the eprints builds you can edit the debian/rules file (the only line you will want is the configure one). Once done you can then type <code>dpkg-buildpackage -rfakeroot</code> from the root dir of the extracted tarball.

This will build you a .deb in the directory above your current location, which can then be installed usinging dpkg:
dpkg -i ../eprints-X.X.X_all.deb

Alternatively you can configure and install it yourself (a non debian specific version) by configuring manually and then running install.pl:
$ ./configure --with-smtp-server=smtp.yourdomain
$ sudo ./install.pl

== Operating System Version Specific Requirements ==

=== Ubuntu 18.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 18.04}}

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2023-10-14T11:18:34Z

Ajm: Moved RPM installation method section to after Source Installation method section.

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 18.04 LTS, 20.04 LTS or 22.04 LTS and (non-LTS versions not recommended)
* Debian 9 (Stretch), 10 (Buster) or Debian 11 (Bullseye) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints:

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-base-bin psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client

Next, create the eprints user

adduser eprints

Now, update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in <code>/etc/apache2/envvars</code>:

export APACHE_RUN_USER=eprints
export APACHE_RUN_GROUP=eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt 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
git checkout tags/v3.4.5

==== EPrints 3.3.x for GitHub ====

apt install git
mkdir /opt/eprints3/
chown eprints:eprints /opt/eprints3/
chmod 2775 /opt/eprints3/
su eprints
git clone https://github.com/eprints/eprints.git /opt/eprints3
git checkout tags/v3.3.16

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/2789/7/eprints-3.4.5.tar.gz
tar -xzvf eprints-3.4.5.tar.gz

Then put in the source code in place:

mv eprints-3.4.5 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) 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 Deb package. As new operating systems (e.g. Debian and Ubuntu) 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 Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian 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 Debian package would be all but impossible due to EPrints' high level of customisability.

=== Installing publications flavour ===
EPrints 3.4 DEBs 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/

=== Configuration ===
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 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.

=== Useful commands for source development and testing ===
The following commands may be useful for those developing or testing EPrints but are not necessary for installing EPrints.
==== Install EPrints build dependencies ====
apt-get build-dep eprints
==== Get EPrints source ====
apt-get source eprints
==== Rebuilding ====
To change the way the eprints builds you can edit the debian/rules file (the only line you will want is the configure one). Once done you can then type <code>dpkg-buildpackage -rfakeroot</code> from the root dir of the extracted tarball.

This will build you a .deb in the directory above your current location, which can then be installed usinging dpkg:
dpkg -i ../eprints-X.X.X_all.deb

Alternatively you can configure and install it yourself (a non debian specific version) by configuring manually and then running install.pl:
$ ./configure --with-smtp-server=smtp.yourdomain
$ sudo ./install.pl

== Operating System Version Specific Requirements ==

=== Ubuntu 18.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 18.04}}

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2023-10-14T11:14:13Z

Ajm: /* Downloading and Deploying EPrints Source */ Changed the order, so the two preferred methods came first.

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 18.04 LTS, 20.04 LTS or 22.04 LTS and (non-LTS versions not recommended)
* Debian 9 (Stretch), 10 (Buster) or Debian 11 (Bullseye) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) 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 Deb package. As new operating systems (e.g. Debian and Ubuntu) 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 Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian 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 Debian package would be all but impossible due to EPrints' high level of customisability.

=== Installing publications flavour ===
EPrints 3.4 DEBs 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints:

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-base-bin psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client

Next, create the eprints user

adduser eprints

Now, update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in <code>/etc/apache2/envvars</code>:

export APACHE_RUN_USER=eprints
export APACHE_RUN_GROUP=eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt 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
git checkout tags/v3.4.5

==== EPrints 3.3.x for GitHub ====

apt install git
mkdir /opt/eprints3/
chown eprints:eprints /opt/eprints3/
chmod 2775 /opt/eprints3/
su eprints
git clone https://github.com/eprints/eprints.git /opt/eprints3
git checkout tags/v3.3.16

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/2789/7/eprints-3.4.5.tar.gz
tar -xzvf eprints-3.4.5.tar.gz

Then put in the source code in place:

mv eprints-3.4.5 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

=== Configuration ===
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 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.

=== Useful commands for source development and testing ===
The following commands may be useful for those developing or testing EPrints by are not necessary for installing EPrints.
==== Install EPrints build dependencies ====
apt-get build-dep eprints
==== Get EPrints source ====
apt-get source eprints
==== Rebuilding ====
To change the way the eprints builds you can edit the debian/rules file (the only line you will want is the configure one). Once done you can then type <code>dpkg-buildpackage -rfakeroot</code> from the root dir of the extracted tarball.

This will build you a .deb in the directory above your current location, which can then be installed usinging dpkg:
dpkg -i ../eprints-X.X.X_all.deb

Alternatively you can configure and install it yourself (a non debian specific version) by configuring manually and then running install.pl:
$ ./configure --with-smtp-server=smtp.yourdomain
$ sudo ./install.pl

== Operating System Version Specific Requirements ==

=== Ubuntu 18.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 18.04}}

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2023-10-14T11:11:06Z

Ajm: /* Dependencies and Pre-configuration */ Swapped links around - now 3.4 link is before the 3.3 link.

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 18.04 LTS, 20.04 LTS or 22.04 LTS and (non-LTS versions not recommended)
* Debian 9 (Stretch), 10 (Buster) or Debian 11 (Bullseye) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) 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 Deb package. As new operating systems (e.g. Debian and Ubuntu) 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 Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian 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 Debian package would be all but impossible due to EPrints' high level of customisability.

=== Installing publications flavour ===
EPrints 3.4 DEBs 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints:

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-base-bin psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client

Next, create the eprints user

adduser eprints

Now, update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in <code>/etc/apache2/envvars</code>:

export APACHE_RUN_USER=eprints
export APACHE_RUN_GROUP=eprints

=== Downloading and Deploying EPrints Source ===
==== EPrints 3.3.x for GitHub ====

apt install git
mkdir /opt/eprints3/
chown eprints:eprints /opt/eprints3/
chmod 2775 /opt/eprints3/
su eprints
git clone https://github.com/eprints/eprints.git /opt/eprints3
git checkout tags/v3.3.16

==== EPrints 3.4.x for GitHub ====

apt 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
git checkout tags/v3.4.5

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/2789/7/eprints-3.4.5.tar.gz
tar -xzvf eprints-3.4.5.tar.gz

Then put in the source code in place:

mv eprints-3.4.5 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

=== Configuration ===
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 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.

=== Useful commands for source development and testing ===
The following commands may be useful for those developing or testing EPrints by are not necessary for installing EPrints.
==== Install EPrints build dependencies ====
apt-get build-dep eprints
==== Get EPrints source ====
apt-get source eprints
==== Rebuilding ====
To change the way the eprints builds you can edit the debian/rules file (the only line you will want is the configure one). Once done you can then type <code>dpkg-buildpackage -rfakeroot</code> from the root dir of the extracted tarball.

This will build you a .deb in the directory above your current location, which can then be installed usinging dpkg:
dpkg -i ../eprints-X.X.X_all.deb

Alternatively you can configure and install it yourself (a non debian specific version) by configuring manually and then running install.pl:
$ ./configure --with-smtp-server=smtp.yourdomain
$ sudo ./install.pl

== Operating System Version Specific Requirements ==

=== Ubuntu 18.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 18.04}}

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2023-10-14T11:08:20Z

Ajm: /* Dependencies and Pre-configuration */ Changed production warning to production endorsement.

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 18.04 LTS, 20.04 LTS or 22.04 LTS and (non-LTS versions not recommended)
* Debian 9 (Stretch), 10 (Buster) or Debian 11 (Bullseye) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) 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 Deb package. As new operating systems (e.g. Debian and Ubuntu) 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 Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian 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 Debian package would be all but impossible due to EPrints' high level of customisability.

=== Installing publications flavour ===
EPrints 3.4 DEBs 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via [https://github.com/eprints/eprints EPrints 3.3] or [https://github.com/eprints/eprints3.4 EPrints 3.4] Core Git repositories, and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints:

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-base-bin psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client

Next, create the eprints user

adduser eprints

Now, update Apache configuration to set it up to use the eprints user and group, by ensuring the following lines are set thus in <code>/etc/apache2/envvars</code>:

export APACHE_RUN_USER=eprints
export APACHE_RUN_GROUP=eprints

=== Downloading and Deploying EPrints Source ===
==== EPrints 3.3.x for GitHub ====

apt install git
mkdir /opt/eprints3/
chown eprints:eprints /opt/eprints3/
chmod 2775 /opt/eprints3/
su eprints
git clone https://github.com/eprints/eprints.git /opt/eprints3
git checkout tags/v3.3.16

==== EPrints 3.4.x for GitHub ====

apt 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
git checkout tags/v3.4.5

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/2789/7/eprints-3.4.5.tar.gz
tar -xzvf eprints-3.4.5.tar.gz

Then put in the source code in place:

mv eprints-3.4.5 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

=== Configuration ===
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 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.

=== Useful commands for source development and testing ===
The following commands may be useful for those developing or testing EPrints by are not necessary for installing EPrints.
==== Install EPrints build dependencies ====
apt-get build-dep eprints
==== Get EPrints source ====
apt-get source eprints
==== Rebuilding ====
To change the way the eprints builds you can edit the debian/rules file (the only line you will want is the configure one). Once done you can then type <code>dpkg-buildpackage -rfakeroot</code> from the root dir of the extracted tarball.

This will build you a .deb in the directory above your current location, which can then be installed usinging dpkg:
dpkg -i ../eprints-X.X.X_all.deb

Alternatively you can configure and install it yourself (a non debian specific version) by configuring manually and then running install.pl:
$ ./configure --with-smtp-server=smtp.yourdomain
$ sudo ./install.pl

== Operating System Version Specific Requirements ==

=== Ubuntu 18.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 18.04}}

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on RHEL/Fedora/CentOS

2023-10-14T10:58:59Z

Ajm: /* Non-critical Dependencies */ not included as part of the RPM installation -> not included as part of the installation process

[[Category:Installation]]

==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 [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:

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
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 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 8}}

=== RHEL / CentOS / Rocky 9 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 9}}

== 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 (<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 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.

Installing EPrints on RHEL/Fedora/CentOS

2023-10-14T10:57:46Z

Ajm: Moved RPM installation method section to after Source Installation method section.

[[Category:Installation]]

==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 [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:

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

* '''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 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 8}}

=== RHEL / CentOS / Rocky 9 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 9}}

== 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 (<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 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.

Installing EPrints on RHEL/Fedora/CentOS

2023-10-14T10:53:59Z

Ajm: /* Installing EPrints 3.4.x from Source */ Brought the recommendation for production use from the end of the second sentence, to the start of it.

[[Category:Installation]]

==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 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.

== Installing EPrints 3.4.x from Source ==
'''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:

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

* '''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]].

== Operating System Version Specific Requirements ==

=== RHEL / CentOS 7 ===
No significant issues.

=== 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 ==
* 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 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.

Installing EPrints on RHEL/Fedora/CentOS

2023-10-14T10:47:33Z

Ajm: /* Installing EPrints 3.4.x from Source */ Reworded warning against production use into endorsement for production use.

[[Category:Installation]]

==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 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.

== Installing EPrints 3.4.x from Source ==
'''Ideally you will install from source from [https://github.com/eprints/eprints3.4 EPrints Core Git repository]. Installing from source was previously most useful for those wishing to develop EPrints code or a plugin or Bazaar package, and is now the preferred way to install for production repositories 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
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 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.

* '''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]].

== Operating System Version Specific Requirements ==

=== RHEL / CentOS 7 ===
No significant issues.

=== 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 ==
* 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 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.

Installing EPrints on RHEL/Fedora/CentOS

2023-10-09T19:45:49Z

Ajm: /* Troubleshooting */ - minor typo edits - (in successful -> is successful) - (can access -> cannot access)

[[Category:Installation]]

==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 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 https://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/.
dnf install eprints-3.4.4-1.el7.noarch.rpm

=== 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/
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 ==
'''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].'''

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

* '''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]].

== Operating System Version Specific Requirements ==

=== RHEL / CentOS 7 ===
No significant issues.

=== 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 ==
* 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 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.

Installing EPrints on RHEL/Fedora/CentOS

2023-10-04T13:52:50Z

Ajm: /* Troubleshooting */ Added a note about DNS Wildcards in quasi-colloquial language, potentially due to a small amount of Pepsi Max Cherry having had a disproportionally large effect on me today, partially mitigated by limiting this addition to 1 sentence

[[Category:Installation]]

==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 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 https://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/.
dnf install eprints-3.4.4-1.el7.noarch.rpm

=== 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/2789/2/eprints-3.4.5-flavours.tar.gz
tar -xzvf eprints-3.4.5-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.5/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.5/
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 ==
'''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].'''

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

* '''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]].

== Operating System Version Specific Requirements ==

=== RHEL / CentOS 7 ===
No significant issues.

=== 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 ==
* 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 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.

Issues with installing EPrints on RHEL / CentOS / Rocky 9

2023-10-04T12:37:44Z

Ajm: /* Compatibility issues with XML::LibXSLT */ changed "generate a segmentation fault when you..." to "generate a segmentation fault and core dump when you..."

==== elinks package is no longer available ====
The RPM package <tt>elinks</tt> is no longer available in RHEL / CentOS / Rocky 9 even with EPEL package repository. <tt>elinks</tt> 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 <tt>html2text</tt> rather than <tt>elinks</tt>. [https://github.com/eprints/eprints3.4/commit/ce5bc101e2212f2b3dd5c0c7cc2b058803bdb79a|This changeset] shows how the places where <tt>elinks</tt> is used can be changed to switch over to using <tt>html2text</tt>. To make use of this you will need to add <tt>python3-html2text</tt> to the DNF command above.

==== perl-IO-String package is no longer available ====
The RPM package <tt>perl-IO-String</tt> 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 <tt>perl-IO-String</tt> 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 <tt>crb</tt> repository:

dnf config-manager --set-enabled crb

Then install <tt>perl-IO-String</tt>:

dnf install perl-IO-String

==== Sub-dependency packages perl-MIME-Types and perl-Digest-SHA1 are no longer available ====
<tt>perl-MIME-Lite</tt> package requires <tt>perl-MIME-Types</tt> package and <tt>perl-Apache-DBI</tt> requires <tt>perl-Digest-SHA1</tt> 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 <tt>crb</tt> repository:

dnf config-manager --set-enabled crb

Then install <tt>perl-MIME-Types</tt> and <tt>perl-Digest-SHA1</tt>:

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

==== perl-Apache-DBI and Pod::LaTeX packages is no longer available ====
The RPM packages <tt>perl-Apache-DBI</tt> 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 <tt>XML::LibXSLT</tt> either through the <tt>perl-XML-LibXSLT</tt> RPM or CPAN causes <tt>httpd</tt> to generate a segmentation fault and core dump when you try to start it. The most straightfarward solution to this is to run <tt>httpd</tt> in <tt>mpm-prefork</tt> rather than <tt>mpm-event</tt> mode. This can be acheived by editing <tt>/etc/httpd/conf.modules.d/00-mpm.conf</tt> and commenting out the following line:
LoadModule mpm_event_module modules/mod_mpm_event.so
and uncommenting the <tt>mpm-prefork</tt> line:
LoadModule mpm_prefork_module modules/mod_mpm_prefork.so
The alternative solution is to make sure that <tt>XML::LibXSLT</tt> is not installed through the <tt>perl-XML-LibXSLT</tt> 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;

Adding a Field to a Live Repository

2023-07-17T17:24:06Z

Ajm: Line return adjustments.

[[Category:Manual]]
[[Category:Metadata Fields]]
[[Category: Out of Date]]

=== EPrints 3.3+ ===

Follow the instructions as you would for [[HOW TO: Add a New Field]].

As described there, you define your new fields in...
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl</code> for EPrint-level metadata,
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/document_fields.pl</code> for document-level metadata (this file doesn't exist by default, but is honoured),
* and <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_fields.pl</code> for user metadata, etc etc.

Since a repository's <code>eprint_fields.pl</code> will override a flavour's <code>eprint_fields.pl</code> based on them both having the same file name, should you only wish to add to a flavour's fields rather than replace them, you may prefer to give your archive's local version a file name such as <code>eprint_fields_local.pl</code>, and then inside have only your new field(s):

push @{$c->{fields}->{eprint}},

{
name => 'my_first_new_field',
type => 'set',
options => [
'yes',
'no',
'partial',
],
input_rows => 1,
},

{
name => 'my_second_new_field',
type => 'set',
options => [
'yes',
'no',
'partial',
],
input_rows => 1,
},

;

Simply make sure your <code>push</code>, is adding your field to the correct dataset you wish to add fields to - in this case an <code>eprint</code> dataset.

Then, once you have added your new field definitions to the appropriate configuration file you can run ''update'' via [[API:bin/epadmin|epadmin]] from the shell.

You can begin with a dry run to see what would happen:

./bin/epadmin update_dry_run ARCHIVEID

Then once confident proceed for real:

./bin/epadmin update ARCHIVEID

=== EPrints 3.1+ ===

EPrint 3.3's ''update'' is a synonym of the ''update_database_structure'' method available from Eprints 3.1+:

./bin/epadmin update_database_structure ARCHIVEID

=== EPrints 3.0 ===

To add a field to a live eprints archive in Eprints 3.0 you have to modify the SQL tables.
Before you start this, you may wish to BackupTheDatabase.

* Add the new columns to the appropriate tables. There are no longer four separate tables for eprints as there were in EP2 (<code>archive</code>, <code>buffer</code> etc), so it's simpler.
** For a field defined in <code>eprint_fields.pl</code>, the tables are <code>eprint</code> and <code>eprint__ordervalues_en</code> (replacing <code>en</code> with your language as required).
** For a field defined in <code>document_fields.pl</code>, you want <code>document</code> and <code>document__ordervalues_en</code>.
** And so on...
* The column types are the same as for EP2, ie in <code>eprint</code> you want a type appropriate to the type of your field exactly as described in the Recipe for EP2, while in <code>eprint__ordervalues_en</code> you want <code>text</code> irrespective of your field type.

=== EPrints 2.x ===

See historical versions of this wiki page.

Adding a Field to a Live Repository

2023-07-17T17:21:18Z

Ajm:

Adding a Field to a Live Repository

2023-07-17T17:18:58Z

Ajm: /* EPrints 3.3+ */ - changed 'maybe' option to 'partial' to match previous examples from the page HOW TO: Add a New Field

[[Category:Manual]]
[[Category:Metadata Fields]]
[[Category: Out of Date]]

=== EPrints 3.3+ ===

Follow the instructions as you would for [[HOW TO: Add a New Field]].

As described there, you define your new fields in...
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl</code> for EPrint-level metadata,
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/document_fields.pl</code> for document-level metadata (this file doesn't exist by default, but is honoured),
* and <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_fields.pl</code> for user metadata, etc etc.

Since a repository's <code>eprint_fields.pl</code> will override a flavour's <code>eprint_fields.pl</code> based on them both having the same file name, should you only wish to add to a flavour's fields rather than replace them, you may prefer to give your archive's local version a file name such as <code>eprint_fields_local.pl</code>, and then inside have only your new field(s):

push @{$c->{fields}->{eprint}},

{
name => 'my_first_new_field',
type => 'set',
options => [
'yes',
'no',
'partial',
],
input_rows => 1,
},

{
name => 'my_second_new_field',
type => 'set',
options => [
'yes',
'no',
'partial',
],
input_rows => 1,
},

;

Simply make sure your <code>push</code>, is adding your field to the correct dataset you wish to add fields to - in this case an <code>eprint</code> dataset.

Then, once you have added your new field definitions to the appropriate configuration file you can run ''update'' via [[API:bin/epadmin|epadmin]] from the shell:

./bin/epadmin update ARCHIVEID

=== EPrints 3.1+ ===

EPrint 3.3's ''update'' is a synonym of the ''update_database_structure'' method available from Eprints 3.1+:

./bin/epadmin update_database_structure ARCHIVEID

=== EPrints 3.0 ===

To add a field to a live eprints archive in Eprints 3.0 you have to modify the SQL tables.
Before you start this, you may wish to BackupTheDatabase.

* Add the new columns to the appropriate tables. There are no longer four separate tables for eprints as there were in EP2 (<code>archive</code>, <code>buffer</code> etc), so it's simpler.
** For a field defined in <code>eprint_fields.pl</code>, the tables are <code>eprint</code> and <code>eprint__ordervalues_en</code> (replacing <code>en</code> with your language as required).
** For a field defined in <code>document_fields.pl</code>, you want <code>document</code> and <code>document__ordervalues_en</code>.
** And so on...
* The column types are the same as for EP2, ie in <code>eprint</code> you want a type appropriate to the type of your field exactly as described in the Recipe for EP2, while in <code>eprint__ordervalues_en</code> you want <code>text</code> irrespective of your field type.

=== EPrints 2.x ===

See historical versions of this wiki page.

HOW TO: Add a New Field

2023-07-17T17:17:04Z

Ajm: Removed mention of needing to do SQL hacking. Referred to the need to run epadmin update if the repository is live.

This covers adding a new field to a new system. When adding to a live system, you may wish to follow up with an epadmin update command, as documented in [[Adding a Field to a Live Repository]].

In this example we add a new "set" field called "local" which will have 3 options "yes","no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

= Add the Field to archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl =

Add the field to the appropriate part of eprint_fields.pl

{
'name' => 'local',
'type' => 'set',
'options' => [
'yes',
'no',
'partial',
],
'input_rows' => 1,
},

input_rows being set to one will make it appear as a pull-down menu.

= Add the Field to Workflow =

If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in archives/ARCHIVEID/cfg/workflows/eprint/default.xml (this can be changed on a live system without any serious consequencies). Add the following to an approriate place in the core section:

<component><field ref="local" required="yes" /></component>

= Add the Field Information to the Archive Phrase File(s) =

Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language). Phrases for eprint fields are found in archives/ARCHIVEID/cfg/lang/en/phrases/eprint_fields.xml.

<epp:phrase id="eprint_fieldname_local">Produced Locally</epp:phrase>
<epp:phrase id="eprint_fieldhelp_local">Please indicate if this item was
produces in the foo organisation, or not.</epp:phrase>
<epp:phrase id="eprint_fieldopt_local_yes">produced locally</epp:phrase>
<epp:phrase id="eprint_fieldopt_local_no">not produced locally</epp:phrase>
<epp:phrase id="eprint_fieldopt_local_partial">only partially produced
locally</epp:phrase>

== Other things you may wish to change after adding a new field ==

= Add it to the citations file =

This is optional, only do this if you want it to appear in the citated forms.

In our example case we only want this to appear when citing technical reports, so we add the following to archives/ARCHIVEID/cfg/lang/en/phrases/eprint_fields.xml:

<if test="type = 'techreport'">
<print expr="local"/>
</if>

The <print> element is not inside <if test="local"></if> as it is a required field and will (should) always be set.

= Add it to the the Abstract (or View-User) page =

This is also optional. If you want it to appear on the web page for this item then edit either archives/ARCHIVEID/cfg/cfg.d/eprint_render.pl or archives/ARCHIVEID/cfg/cfg.d/user_render.pl.

In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...

Single language example:

if( $eprint->get_value( "local" ) ne "yes" )
{
# don't need to "my $p" as it's done earlier.
$p = $session->make_element( "p" );
$p->appendChild( $session->make_text( "This item was " ) );
$p->appendChild( $eprint->render_value( "local" ) );
$p->appendChild( $session->make_text( "." ) );

# Append our new paragraph to the page.
$page->appendChild( $p );
}

Multiple-language example:

If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

<epp:phrase id="page:itemnotlocal"><p>This item was <pin ref="status" />.</p></epp:phrase>

And to the archives/ARCHIVEID/cfg/cfg.d/eprint_render.pl file:

if( $eprint->get_value( "local" ) ne "yes" )
{
my $localmsg = $session->html_phrase(
"page:itemnotlocal",
status=>$eprint->render_value( "local" ) );
$page->appendChild( $localmsg );
}

You may prefer to use this method even if you are only using a single language.

[[Category:Metadata Fields]] [[Category:Customisation]]

Adding a Field to a Live Repository

2023-07-17T17:08:19Z

Ajm: Brought the most recent documentation to the top, so the warnings about needing to modify the SQL tables was clearly referring to 3.0 and not 3.3+.

[[Category:Manual]]
[[Category:Metadata Fields]]
[[Category: Out of Date]]

=== EPrints 3.3+ ===

Follow the instructions as you would for [[HOW TO: Add a New Field]].

As described there, you define your new fields in...
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/eprint_fields.pl</code> for EPrint-level metadata,
* <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/document_fields.pl</code> for document-level metadata (this file doesn't exist by default, but is honoured),
* and <code>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_fields.pl</code> for user metadata, etc etc.

Since a repository's <code>eprint_fields.pl</code> will override a flavour's <code>eprint_fields.pl</code> based on them both having the same file name, should you only wish to add to a flavour's fields rather than replace them, you may prefer to give your archive's local version a file name such as <code>eprint_fields_local.pl</code>, and then inside have only your new field(s):

push @{$c->{fields}->{eprint}},

{
name => 'my_first_new_field',
type => 'set',
options => [
'yes',
'no',
'maybe',
],
input_rows => 1,
},

{
name => 'my_second_new_field',
type => 'set',
options => [
'yes',
'no',
'maybe',
],
input_rows => 1,
},

;

Simply make sure your <code>push</code>, is adding your field to the correct dataset you wish to add fields to - in this case an <code>eprint</code> dataset.

Then, once you have added your new field definitions to the appropriate configuration file you can run ''update'' via [[API:bin/epadmin|epadmin]] from the shell:

./bin/epadmin update ARCHIVEID

=== EPrints 3.1+ ===

EPrint 3.3's ''update'' is a synonym of the ''update_database_structure'' method available from Eprints 3.1+:

./bin/epadmin update_database_structure ARCHIVEID

=== EPrints 3.0 ===

To add a field to a live eprints archive in Eprints 3.0 you have to modify the SQL tables.
Before you start this, you may wish to BackupTheDatabase.

* Add the new columns to the appropriate tables. There are no longer four separate tables for eprints as there were in EP2 (<code>archive</code>, <code>buffer</code> etc), so it's simpler.
** For a field defined in <code>eprint_fields.pl</code>, the tables are <code>eprint</code> and <code>eprint__ordervalues_en</code> (replacing <code>en</code> with your language as required).
** For a field defined in <code>document_fields.pl</code>, you want <code>document</code> and <code>document__ordervalues_en</code>.
** And so on...
* The column types are the same as for EP2, ie in <code>eprint</code> you want a type appropriate to the type of your field exactly as described in the Recipe for EP2, while in <code>eprint__ordervalues_en</code> you want <code>text</code> irrespective of your field type.

=== EPrints 2.x ===

See historical versions of this wiki page.

EPrints Ingredients

2023-07-17T10:15:27Z

Ajm: Readability improvements: need be tied to -> needn't be tied to; but also -> and also; this files -> these files; EPrints copyright -> EPrints' copyright

EPrints Ingredients were added in EPrints 3.4 as a means of providing complex functionality that was not suited to being provided by [https://bazaar.eprints.org Bazaar] plugins with their one-click install. This is because certain functionality (e.g. [[Coversheets]]) requires both EPrints and non-EPrints dependencies and complex configuration to be useful.

EPrints Zero includes the ''bazaar'' ingredient by default and it is enabled in the publication flavour's '''inc''' file. From EPrints 3.4.3, a ''jquery'' ingredient is included to package a known version of [https://jquery.com/ jQuery]. This is not enabled in the publication flavour's '''inc''' file, as it only need be enabled if you intend to use jQuery within your repository for specific branding requirements.

From 3.4.4 a ''prototypejs'' ingredient is included, which is also enabled in the publication flavour's '''inc'''. This must be added to your repository's flavour's '''inc''' file if you are upgrading from an earlier version of EPrints 3.4, as it includes the Prototype and Scriptaculous JavaScript libraries underlying EPrints' JavaScript API. The reason for the moving to an ingredient is so that in future EPrints' JavaScript API needn't be tied to a specific JavaScript library and also to simplify copyright and licensing as these files are not subject to EPrints' copyright and license statements.

[[Category:Customisation]]

EPrints Ingredients

2023-07-17T10:10:59Z

Ajm: typo correction: added your -> added to your

EPrints Ingredients were added in EPrints 3.4 as a means of providing complex functionality that was not suited to being provided by [https://bazaar.eprints.org Bazaar] plugins with their one-click install. This is because certain functionality (e.g. [[Coversheets]]) requires both EPrints and non-EPrints dependencies and complex configuration to be useful.

EPrints Zero includes the ''bazaar'' ingredient by default and it is enabled in the publication flavour's '''inc''' file. From EPrints 3.4.3, a ''jquery'' ingredient is included to package a known version of [https://jquery.com/ jQuery]. This is not enabled in the publication flavour's '''inc''' file, as it only need be enabled if you intend to use jQuery within your repository for specific branding requirements.

From 3.4.4 a ''prototypejs'' ingredient is included, which is also enabled in the publication flavour's '''inc'''. This must be added to your repository's flavour's '''inc''' file if you are upgrading from an earlier version of EPrints 3.4, as it includes the Prototype and Scriptaculous JavaScript libraries underlying EPrints' JavaScript API. The reason for the moving to an ingredient is so that in future EPrints' JavaScript API need be tied to a specific JavaScript library but also to simplify copyright and licensing as this files are not subject to EPrints copyright and license statements.

[[Category:Customisation]]

EPrints Ingredients

2023-07-17T10:09:15Z

Ajm: Typo correction: there one-click install -> their one-click install

EPrints Ingredients were added in EPrints 3.4 as a means of providing complex functionality that was not suited to being provided by [https://bazaar.eprints.org Bazaar] plugins with their one-click install. This is because certain functionality (e.g. [[Coversheets]]) requires both EPrints and non-EPrints dependencies and complex configuration to be useful.

EPrints Zero includes the ''bazaar'' ingredient by default and it is enabled in the publication flavour's '''inc''' file. From EPrints 3.4.3, a ''jquery'' ingredient is included to package a known version of [https://jquery.com/ jQuery]. This is not enabled in the publication flavour's '''inc''' file, as it only need be enabled if you intend to use jQuery within your repository for specific branding requirements.

From 3.4.4 a ''prototypejs'' ingredient is included, which is also enabled in the publication flavour's '''inc'''. This must be added your repository's flavour's '''inc''' file if you are upgrading from an earlier version of EPrints 3.4, as it includes the Prototype and Scriptaculous JavaScript libraries underlying EPrints' JavaScript API. The reason for the moving to an ingredient is so that in future EPrints' JavaScript API need be tied to a specific JavaScript library but also to simplify copyright and licensing as this files are not subject to EPrints copyright and license statements.

[[Category:Customisation]]

Issues with installing EPrints on RHEL / CentOS / Rocky 9

2023-07-04T17:19:28Z

Ajm: Typo correction on /* MySQL root user cannot be used */ - as follows: The get round this -> To get round this

==== elinks package is no longer available ====
The RPM package <tt>elinks</tt> is no longer available in RHEL / CentOS / Rocky 9 even with EPEL package repository. <tt>elinks</tt> 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 <tt>html2text</tt> rather than <tt>elinks</tt>. [https://github.com/eprints/eprints3.4/commit/ce5bc101e2212f2b3dd5c0c7cc2b058803bdb79a|This changeset] shows how the places where <tt>elinks</tt> is used can be changed to switch over to using <tt>html2text</tt>. To make use of this you will need to add <tt>python3-html2text</tt> to the DNF command above.

==== perl-IO-String package is no longer available ====
The RPM package <tt>perl-IO-String</tt> 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 <tt>perl-IO-String</tt> 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 <tt>crb</tt> repository:

dnf config-manager --set-enabled crb

Then install <tt>perl-IO-String</tt>:

dnf install perl-IO-String

==== Sub-dependency packages perl-MIME-Types and perl-Digest-SHA1 are no longer available ====
<tt>perl-MIME-Lite</tt> package requires <tt>perl-MIME-Types</tt> package and <tt>perl-Apache-DBI</tt> requires <tt>perl-Digest-SHA1</tt> 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 <tt>crb</tt> repository:

dnf config-manager --set-enabled crb

Then install <tt>perl-MIME-Types</tt> and <tt>perl-Digest-SHA1</tt>:

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

==== perl-Apache-DBI and Pod::LaTeX packages is no longer available ====
The RPM packages <tt>perl-Apache-DBI</tt> 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 <tt>XML::LibXSLT</tt> either through the <tt>perl-XML-LibXSLT</tt> or through CPAN causes <tt>httpd</tt> to generate a segmentation fault when you try to start it. The most straightfoarward solution to this is to run <tt>httpd</tt> in <tt>mpm-prefork</tt> rather than <tt>mpm-event</tt> mode. This can be acheived by editing <tt>/etc/httpd/conf.modules.d/00-mpm.conf</tt> and commenting out the following line:
LoadModule mpm_event_module modules/mod_mpm_event.so
and uncommenting the <tt>mpm-prefork</tt> line:
LoadModule mpm_prefork_module modules/mod_mpm_prefork.so

==== 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;

Getting Started with EPrints 3

2023-07-04T13:46:58Z

Ajm: Typo correction in "Running epadmin...Create an initial user...Enter a username" section as follows: The username you will be used -> The username you will use

[[Category:Manual]]
[[Category:Management]]
[[Category:Installation]]
==Creating an Archive==

EPrints 3 can run multiple archives under one install. Multiple archives will require giving additional DNS aliases to the machine running EPrints, EPrints can then create all the parts of the apache configuration file needed to run the virtual hosts.

Alternatively you can use different ports to distinguish your different repositories hosted by the same server.

===Running epadmin===
Make sure MySQL is actually running.

Change to your eprints user (probably ''eprints'').

Change directory to the eprints directory (<tt>/opt/eprints3</tt> by default for a source install and <tt>/usr/share/eprints</tt> for packaged installs) and run

bin/epadmin create

If you are running EPrints 3.4 or later you will need a further parameter to define which flavour of repository you want. The common two choices are either '''pub''' or '''zero''':

bin/epadmin create pub

You will get the following prompts (note that when you see something in [square brackets], it's the default value and can be selected by simply hitting <enter>):

* Archive ID - the system name for your archive. It's probably a good idea to think of something short and memorable. Once entered, an <tt>archive/<archive_id></tt> directory will be created, and the standard configuration files will be copied in.
* Configure vital settings - Hit enter to say 'yes'. This will lead to more prompting about core settings:
** Hostname - What someone will type into a web browser to get to your archive. Make sure that your systems team have a DNS alias pointing to your server for this.
** Webserver Port - Which port do you want to serve the archive on? The default is 80, so unless you can think of a good reason not to, just hit enter to accept the default.
** Alias - You can enter any number of aliases that will take users to this archive. Enter a '#' when you don't want to enter any more. You could have your archive served on <tt>eprints.myorganisation.org</tt> and <tt>eprints.myorg.org</tt>. As with the Hostname, your systems team need to be informed about these aliases too.
*** Redirect ''your chosen alias'' to ''Hostname'' - Yes, usually that is your intention.
** Please enter the path part of the repository's base URL - Make it simple for you and your visitors ... and confirm the suggestion; multiple archives could be managed by different domains or ports!
** If you will use https for your user pages (including login) enter the https hostname - No doubt, for secure usage you need another name.
** Administrator Email - Enter the email address of the repository administrator. This will allow your repository users to send email to the right person.
** Archive Name - The full name of your archive. By default, this will be used on many of the pages, and in the title bar of the browser.
** Write these core settings - If you don't say 'yes', then you entered all that data for nothing (relaunch the process by <tt>epadmin config_core ''archive_id''</tt>).
* Configure database - EPrints makes extensive use of a MySQL database. Enter 'yes' to launch <tt>epadmin config_db ''archive_id''</tt>.
** Database Name - The internal name of your database. It makes sense to use the Archive ID for this, but you don't have to. You don't need to create this database, <tt>epadmin</tt> will do it for you.
** MySQL Host - The address of the server that the database is running on. If the database is on the same machine as the EPrints installation, confirm 'localhost'.
** MySQL Port - You probably don't need to enter a value. If you have problems connecting to the database, talk to your systems team.
** MySQL Socket - As with MySQL Port, it's unlikely that you need to enter anything.
** Database User - The username with which to log into the MySQL Database. You don't need to create this user, <tt>epadmin</tt> will do it for you. If you enter a MySQL username that already exists, it will be overwritten by epstats!
** Database Password - Just confirm the suggested password for the Database User, <tt>eprints</tt> will keep track of it!
** Write these database settings - You should write them, or you'll lose them.
* Create database <Database Name> - Say ''yes'' to launch <tt>epadmin create_db ''archive_id''</tt>, and <tt>epadmin</tt> can create the database and populate it with all the right tables. If you've already created a database and a user for this archive, say 'no'.
** Database Superuser Username - 'root' isn't a bad suggestion, but should match your specifications during the MySQL installation.
** Database Superuser Password - To create the database and the user, epadmin needs the MySQL Root Password (specified during MySQL installation). This is not saved anywhere. It is only used to log into MySQL, create the database and create the user with useful access rights. The password is forgotten afterwards, because it's not needed anymore by this process!
* Create database tables - say 'yes' to have epadmin create all the database tables, i.e. initiate the same as with <tt>epadmin create_tables ''archive_id''</tt>.
* Create an initial user - It's a good idea to create a user account for yourself at this point, but you can start the same process by <tt>epadmin create_user ''archive_id''</tt> anytime ...
** Enter a username - The username you will use to log into EPrints on the home page of the new archive.
** Select a user type (user|editor|admin) - There are three user roles in EPrints. You probably want to be an administrator, so enter 'admin'.
** Enter Password - A password for this user. Remember to choose a password that will be hard for someone else to guess!
** Email - Enter your email address so that users can get in contact with you.
* Do you want to build the static web pages - There are a number of pages in EPrints which change very rarely. These are the static pages. The Home page and the About page are examples of static pages. Stylesheets are also static. These pages need to be built, so say 'yes' (otherwise you have to start that process manually later by <tt>generate_static ''archive_id''</tt>).
* Do you want to import the LOC subjects - If you will be using the Library Of Congress subject hierarchy, say 'yes'. Otherwise you will need to create your own subject hierarchy and import it using [http://wiki.eprints.org/w/API:bin/import_subjects <tt>import_subjects</tt>].
* Do you want to update the apache config files? (you still need to add the 'Include' line in the very central http.conf, e.g.) - Your archive has a number of files which it uses to configure the web server. These should be updated, so say ''yes'' or start <tt>generate_apacheconf ''archive_id''</tt> later.
* Before exiting, <tt>epadmin</tt> will display information about configuring the webserver.

====example configuration====

The script will run through a number of configuration options, an example of which is listed below. Please change the settings to suit your site configuration.

<pre>
-bash-4.1$ ./bin/epadmin create

Create an EPrint Repository

Please select an ID for the repository, which will be used to create a directory
and identify the repository. Lower case letters and numbers, may not start with
a number. examples: "lemurprints" or "test3"

Archive ID? testrepo
We need to create /usr/share/eprints/archives/testrepo, doing it now…

Creating initial files:
Installing: /usr/share/eprints/archives/testrepo/cfg
Installing: /usr/share/eprints/archives/testrepo/cfg/lang
[...]
Installing: /usr/share/eprints/archives/testrepo/cfg/workflows/eprint

Ok. I've created the initial config files and directory structure.
I've also created a "disk0" directory under documents/ if you want
your full texts to be stored on a different partition then remove
the disk0, and create a symbolic link to the directory you wish to
store the full texts in. Additional links may be placed here to be
used when the first is full.

Configure vital settings? [yes] ?
Core configuration for testrepo

Please enter the fully qualified hostname of the repository.

For a production system we recommend against using the real hostname of the
machine.

Example: testrepo.footle.ac.uk

Hostname? testprint

Please enter the port of the webserver. This is probably 80, but you may wish
to run apache on a different port if you are experimenting.

Webserver Port [80] ?

Please enter all the aliases which could reach the repository, and indicate if
you would like EPrints to write a Redirect Rule to redirect requests to this
alias to the correct URL.
Some suggestions:
centos610.local
centos610
centos610

Enter a single hash (#) when you're done.

Alias (enter # when done) [#] ? testprint.local
Redirect testprint.local to testprint [yes] ?

Alias (enter # when done) [#] ?

Please enter the path part of the repository's base URL. This should probably
be '/'.

Path [/] ?

If you will use https for your user pages (including login) enter the https hostname
here, or leave blank when using http only.

HTTPS Hostname [] ?

Administrator Email? someone@example.com

Enter the name of the repository in the default language. If you wish to enter
other titles for other languages or enter non ascii characters then you may
enter something as a placeholder and edit the XML config file which this
script generates.

Archive Name [Test Repository] ?

Write these core settings? [yes] ?
Wrote /usr/share/eprints/archives/testrepo/cfg/cfg.d/adminemail.pl
Wrote /usr/share/eprints/archives/testrepo/cfg/cfg.d/10_core.pl
Wrote /usr/share/eprints/archives/testrepo/cfg/lang/en/phrases/archive_name.xml

Configure database? [yes] ?

Configuring Database for: testrepo
Database Name [testrepo] ?
MySQL Host [localhost] ?

You probably don't need to set socket and port (unless you do!?).
MySQL Port (# for no setting) [#] ?
MySQL Socket (# for no setting) [#] ?
Database User [testrepo] ?
Database Password [nxxxxuAw] ?
Database Engine [MyISAM] ?

Write these database settings? [yes] ?
Wrote /usr/share/eprints/archives/testrepo/cfg/cfg.d/database.pl

EPrints can create the database, and grant the correct permissions.

Create database "testrepo" [yes] ?
Database Superuser Username [root] ?
Database Superuser Password?
Create database tables? [yes] ?
Creating database tables...
Set DB compatibility flag to '3.3.4'.
Done creating database tables.

Create an initial user? [yes] ?
Creating a new user in testrepo

Enter a username [admin] ?
Select a user type (user|editor|admin) [admin] ?
Enter Password?
Email? first.last@example.org

Successfully created new user:
ID: 1
Do you want to build the static web pages? [yes] ?

Starting EPrints Repository.
Connecting to DB ... done.
mkdir /usr/share/eprints/archives/testrepo/html/en/codemirror/mode/velocity
/usr/share/eprints/lib/static/codemirror/mode/velocity/velocity.js -> /usr/share/eprints/archives/testrepo/html/en/codemirror/mode/velocity/velocity.js
mkdir /usr/share/eprints/archives/testrepo/html/en/style/images
/usr/share/eprints/lib/static/style/images/action_edit.png -> /usr/share/eprints/archives/testrepo/html/en/style/images/action_edit.png
[...]
/usr/share/eprints/lib/static/style/images/action_unpack.png -> /usr/share/eprints/archives/testrepo/html/en/style/images/action_unpack.png
/usr/share/eprints/lib/static/codemirror/lib/util/loadmode.js -> /usr/share/eprints/archives/testrepo/html/en/codemirror/lib/util/loadmode.js
Ending EPrints Repository.

Do you want to import the LOC subjects? [yes] ?

Starting EPrints Repository.
Connecting to DB ... done.
Importing from /usr/share/eprints/archives/testrepo/cfg/subjects...
Done importing 280 subjects from /usr/share/eprints/archives/testrepo/cfg/subjects
Reindexing subject dataset to set ancestor data
Reindexing item: subject/A
Reindexing item: subject/AC
Reindexing item: subject/AI
Reindexing item: subject/AM
[...]
Reindexing item: subject/sch_soc
Reindexing item: subject/subjects
Done reindexing
Ending EPrints Repository.

Exiting normally.
Do you want to update the apache config files? (you still need to add the
'Include' line) [yes] ?
Wrote /usr/share/eprints/cfg/apache/testrepo.conf

You must restart apache for any changes to take effect!

--------------------------------------------------------------------------
That seemed to more or less work...
--------------------------------------------------------------------------

Now make any required changes to the cfg files.

Note that changing the metadata configuration may require the database
tables to be regenerated. epadmin erase_data will regenerate the
eprints and documents tables only. erase_data will regenerate everything.
(nb. these also do erase the contents of the tables, and any uploaded
files).

Make sure that your main apache config file contains the line:

Include /usr/share/eprints/cfg/apache.conf

Then stop and start your webserver:
Often:
/etc/rc.d/init.d/httpd stop
/etc/rc.d/init.d/httpd start
(or maybe /usr/local/apache/bin/apachectl stop & start)

And then try connecting to your repository.
--------------------------------------------------------------------------

Don't forget to register your repository at http://roar.eprints.org/

-bash-4.1$

</pre>

Finish apache's configuration before its final restart to be ready for opening a browser and watch the homepage of your new archive, ready to be [[Branding with confidence|branded]].

If you want to add some more users, use the command <tt>epadmin create_user <repository id></tt> or the admin's web dialog.

==Regular Maintenance==

EPrints front end web pages and abstracts '''are ''not'' automatically updated''' when you make changes to the repository.
To apply your changes and update the web pages:

===Generate Views===
eprints@host$ bin/generate_views ''yourarchivename''

===Generate Statics===
eprints@host$ bin/generate_static ''yourarchivename''

===Generate Abstracts===
eprints@host$ bin/generate_abstracts ''yourarchivename''

Finally a restart of your apache server is recommended, because a lot of settings will only be read initially!

EPrints 3.4.5

2023-07-04T10:35:32Z

Ajm: Typo correction in Known Issues section as follows: table take already contains -> table that already contains

{{releasenotes}}

== Release Notes ==
EPrints 3.4.5 is now available on [https://github.com/eprints/eprints3.4/releases/tag/v3.4.5 GitHub] and shortly will be available on files.eprints.org.
* '''Zero codename:''' Smoothie Squall
* '''Publications flavour codename:''' Kombucha Hypercane (1.5)

=== New Dependencies ===
<tt>html2text</tt> RPM / DEB required instead of <tt>elinks</tt>.

Check earlier dependencies for [[EPrints 3.4.4]] and before.

=== Changes Since 3.4.4 ===

==== New Functionality ====
* Adds [[:API:tools/console|console-based REPL tool]]
* [https://github.com/eprints/eprints3.4/issues/290 Adds <code>staged</code> status for indexer tasks so they can be run outside the EPrints indexer. E.g. using a cron job].

==== Security and Privacy Improvements ====
* [https://github.com/eprints/eprints3.4/issues/245 Adds PIN based security for documents].
* [https://github.com/eprints/eprints3.4/issues/246 Makes Xapian index obey <tt>text_index</tt> attribute for fields].
* [https://github.com/eprints/eprints3.4/issues/276 Allows restricted documents to not have their full texts indexed].
* Uses HTTPS for CrossRef lookup of DOIs.
* [https://github.com/eprints/eprints3.4/issues/278 Removes (HTTP only) <code>eprints_session</code> if HTTPS is enabled].
* Improves target URL validation so only local URLs are allowed and not just paths.
* [https://github.com/eprints/eprints3.4/issues/281 Explicitly disables password field autocomplete].
* [https://github.com/eprints/eprints3.4/issues/237 Improves "request copy" security].
* [https://github.com/eprints/eprints3.4/issues/311 Ensures <code>SameSite=Strict</code> for all cookies].
* Better force HTTPS when generating repository URLs.

==== General Improvements ====
* Updates and makes consistent list of software contributors.
* Adds get_search_conditions_not_ex for float fields.
* [https://github.com/eprints/eprints3.4/issues/240 Updates DOCTYPE to be more standards compliant].
* Updates <tt>pub_lib</tt> homepage links for browse views.
* [https://github.com/eprints/eprints3.4/issues/242 Allows MetaField::Subject to have user-defined render_value].
* [https://github.com/eprints/eprints3.4/issues/238 Improves OAI-PMH representation of records that once were live].
* [https://github.com/eprints/eprints3.4/issues/195 Allows <tt>userid</tt> to be logged in Access data objects when user is logged in].
* [https://github.com/eprints/eprints3.4/pull/239 Adds ability to manipulate element attributes].
* [https://github.com/eprints/eprints3.4/pull/244 Updates latest_tool to use filters].
* [https://github.com/eprints/eprints3.4/pull/250 Adds id and classes for individual styling of "Manage records" page].
* [https://github.com/eprints/eprints3.4/pull/252 Adds class attributes for "View details" table].
* [https://github.com/eprints/eprints3.4/pull/254 Adds classnames to navigation items and links].
* [https://github.com/eprints/eprints3.4/issues/256 Splits off <tt>senderemail</tt> from <tt>adminemail</tt> if this need to be different for DMARC reasons].
* [https://github.com/eprints/eprints3.4/issues/261 Adds the optional attributes of resumptionToken in OAI-PMH].
* [https://github.com/eprints/eprints3.4/pull/257 Table class for screens; Status, DatabaseSchema and MetaFieldListing].
* [https://github.com/eprints/eprints3.4/issues/271 Adds <code>--prune</code> option to <code>generate_views</code>].
* Various improvements to <code>check_xapian</code> script including <code>--facets</code> automatically using <code>xapian.facet</code> directory rathe than needing to specify in <code>--path</code>.
* Adds verbose debug to <code>send_alerts</code> to advise when email is not sent as saved search notifications are only required when results are found.
* [https://github.com/eprints/eprints3.4/issues/287 Set canonical URLs for abstract pages for better Google indexing].
* Ensures sitemaps always uses HTTPS URLs if <code>securehost</code> is defined.
* Breaks up show/hide help phrases to make them more compatible with Bootstrap.
* [https://github.com/eprints/eprints3.4/issues/291 Makes task timeout for EPrints' indexer configurable]. Along with making other indexer settings configurable.
* [https://github.com/eprints/eprints3.4/issues/296 Replaces <code>elinks</code> with <code>html2text</code> as application to extract text from HTML/XML files for indexing].
* [https://github.com/eprints/eprints3.4/issues/299 Allows staff search to find results where <code>metadata_visibility</code> is not set to <code>show</code>].
* [https://github.com/eprints/eprints3.4/issues/298 Allows XSL files to be viewed using <code>Config::View::XML</code> plugin].
* [https://github.com/eprints/eprints3.4/issues/249 Allows <code>MetaField::Subject</code>'s <code>top</code> attribute to be set to a configurable function].
* [https://github.com/eprints/eprints3.4/issues/286 Provides overarching setting for maximum file upload size].
* [https://github.com/eprints/eprints3.4/pull/297 Significant phrase changes to facilitate better internationalisation].
* [https://github.com/eprints/eprints3.4/issues/294 Allows screen plugins to use a bespoke page template].
* [https://github.com/eprints/eprints3.4/issues/210 Removes implicit commit when reordering <code>multiple</code> fields].
* [https://github.com/eprints/eprints3.4/issues/304 Adds separate CSS classes to top and bottom action buttons in workflow].
* [https://github.com/eprints/eprints3.4/issues/306 Adds <code>$c->{retain_embargo_dates}</code> settings so dates can be retained when embargoes are lifted without causing any validation warnings or need to perpetually check old embargo dates].
* [https://github.com/eprints/eprints3.4/issues/310 Prevent indexer.log filling up with errors from <code>pdftotext</code>].
* [https://github.com/eprints/eprints3.4/pull/312 Additional CSS classes and IDs added for parts of input forms].
* [https://github.com/eprints/eprints3.4/pull/317 Improvements to phrases used for icons in input forms and views].
* [https://github.com/eprints/eprints3.4/issues/318 Render paragraphs from <code>reason</code>s in emails].
* [https://github.com/eprints/eprints3.4/issues/321 Allow indexcodes to be regenerated as part of <code>epadmin reindex</code> when <code>--force</code> flag is used].
* [https://github.com/eprints/eprints3.4/issues/322 Allow different phrases to be used for field names dependent on eprint's type].
* [https://github.com/eprints/eprints3.4/issues/326 Allows date input fields to be rendered shorter].
* Improves rendering/hiding of missing subjects depending on <code>render_quiet</code>.
* Adds data-row... attributes to compound/multiple field renders.
* Various improvements to POD documentation.

==== Bug Fixes ====
* Fixes typo for <tt>_epname</tt> in RPM spec file.
* [https://github.com/eprints/eprints3.4/issues/243 Adds properly referenced ARIA labels for sets and fields with bespoke <tt>search_input_style</tt>].
* Gets EPrints install script to create <tt>EPRINTS_PATH/tmp</tt> directory with appropriate permissions.
* [https://github.com/eprints/eprints3.4/issues/241 Stops including ARIA <tt>describedby</tt> if help text is empty].
* [https://github.com/eprints/eprints3.4/issues/247 Fixes "Data too long for column 'word'" indexing errors].
* [https://github.com/eprints/eprints3.4/issues/233 Now returns "410 Gone" HTTP code when item has been retired].
* [https://github.com/eprints/eprints3.4/issues/255 Adds missing <code><help></code> and <code><title></code> elements used in phrases for 2nd+ document fields in eprint workflows].
* [https://github.com/eprints/eprints3.4/issues/258 Fixes text indexing <tt>saved_search.spec</tt> causing problems with Xapian].
* [https://github.com/eprints/eprints3.4/issues/262 Fixes HTTPS URLs not be parseable by <code>XML::LibXML->parse_file</code>].
* [https://github.com/eprints/eprints3.4/issues/263 Fixes missing URL encoding of # in filename download links].
* Checks <code>render_dynamic</code> attribute is set for <code>MetaField</code> before testing value
* [https://github.com/eprints/eprints3.4/issues/265 Fixes LDAP-based login failures when accounts need to be created on-the-fly].
* [https://github.com/eprints/eprints3.4/issues/266 Ensures <code>$c->{userhome}</code> and <code>$c->{urlpath}</code> are auto set correctly].
* [https://github.com/eprints/eprints3.4/pull/269 Fixes missing parameter field when making phrase <code>limit_names_shown_label</code>].
* Adds <code>poppler-utils</code> DEB dependency for <code>pdftotext</code> to index PDFs.
* [https://github.com/eprints/eprints3.4/pull/275 Allows <code>PHDTHESIS</code> from BibTeX to be imported without error by correcting mappings for <code>thesis_type</code> and <code>thesis_name</code> fields].
* [https://github.com/eprints/eprints3.4/issues/279 Uses original rather than proxied IP address in access record if proxied address is in (configurable) private IP address range].
* [https://github.com/eprints/eprints3.4/issues/272 Fixes BibTeX import parsing by ignoring entries with empty of malformed citekeys].
* [https://github.com/eprints/eprints3.4/issues/274 Fixes issues with both server-side and client-side caching of JavaScript and CSS auto files].
* [https://github.com/eprints/eprints3.4/issues/284 Fixes search offset being forgotten when results reordered].
* [https://github.com/eprints/eprints3.4/issues/285 Fixes search ordering reverting to "by relevance" when different default ordering is set].
* [https://github.com/eprints/eprints3.4/issues/289 Makes redirects from short URLs to long URLs a 301 rather than 302 or 303]. Good for SEO.
* [https://github.com/eprints/eprints3.4/pull/293 Ensures BibTeX export of <code>note</code> is not prevented is already used by <code>ispublished</code> field].
* [https://github.com/eprints/eprints3.4/pull/295 Fixes incorrect location described in <code>lib/syscfg.d/README</code>].
* Tidies up <code>replyto_name</code> used in emails when referenced user has not set their name.
* [https://github.com/eprints/eprints3.4/issues/301 Fixes disabling <code>Config::Edit</code> plugins breaking "View Configuration"].
* Gracefully handles template pin not being defined or mapped.
* [https://github.com/eprints/eprints3.4/issues/253 Fixes incorrect counts for items for ancestor (e.g. parent) subjects in subject field based browse views].
* [https://github.com/eprints/eprints3.4/pull/292 Fixes bug with grouping function being ignored in certain browse views].
* [https://github.com/eprints/eprints3.4/issues/283 Ensures appropriate escaping in search serialization and setting of <code>$self->{op}</code> for <code>regexp</code> search condition].
* [https://github.com/eprints/eprints3.4/issues/306 Fixes ordering of summary box <code>div</code>s on abstract pages].
* [https://github.com/eprints/eprints3.4/issues/309 CRUD interface GET requests now return <code>NOT_FOUND</code> rather than <code>FORBIDDEN</code> for non-existent eprints].
* [https://github.com/eprints/eprints3.4/pull/314 Removes redundant code from XHTML field rendering function].
* [https://github.com/eprints/eprints3.4/commit/bd0a1e928b70478e4c25f2c818cc77d31b12c98f Ensures consistent ordering of RejectWithEmail / RemoveWithEmail buttons on review queue].
* [https://github.com/eprints/eprints3.4/issues/319 Fixes check for whether JavaScript within uploaded files can run when viewed through EPrints]. Fixes change for [https://github.com/eprints/eprints3.4/issues/62 original issue].
* [https://github.com/eprints/eprints3.4/issues/320 Adds more character mappings for indexer to fix issues with indexing tasks failing to complete due to duplicate index errors].
* [https://github.com/eprints/eprints3.4/commit/ffd9b53079bc6969ba17671552aefd5b5d511c66|Removes unnecessary field defaults. Better restricts digits for int fields].
* [https://github.com/eprints/eprints3.4/pull/325 Fixes ARIA typo in upload form].
* [https://github.com/eprints/eprints3.4/issues/329 Fixes use of fieldsets in input/search from to make it easier and more consistent when modifying CSS].
* [https://github.com/eprints/eprints3.4/issues/330 Deal with UTF8-MB4 characters that would break database queries].
* Makes user menu bar and footer more responsive to page width.
* Fixes word-wrapping overflow on homepage description list.
* Various improvements to the <code>tidy_pids</code> script.
* Various typos

=== Known Issues ===

==== Long time to add <tt>requester_userid</tt> field to access data object ====
Adding new columns to a database table that already contains a lot of records can take a long time. The access table for EPrints can often have tens of millions of records. At such a size adding a new column can take in the order of hours. EPrints 3.4.5 add the new field <tt>requester_userid</tt>. This is intended to capture the logged in user that is viewing or downloading an eprint/document. This is useful for Open Education repositories that have different access permissions. However, if you have a large access table you may want to [https://github.com/eprints/eprints3.4/commit/79683e8dadda91f5d4862b23fa7bd80bcdee081d apply this patch] from the [https://github.com/eprints/eprints3.4/issues/333 GitHub issue].

[[Category:Eprints3.4]]
[[Category:Releases]]