EPrints Documentation - User contributions [en-gb]

Installing EPrints on Debian/Ubuntu

2025-02-24T14:20:26Z

Alex-ball: Remove duplicate listing of libdbd-mysql-perl

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

== Requirements ==
* Ubuntu 20.04 LTS, 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 10 (Buster), Debian 11 (Bullseye) or Debian 12 (Bookworm) - 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 ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page.):

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-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl python3-html2text make libexpat1-dev libxslt1-dev

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

apt-get install mysql-server mysql-client libmysqlclient-dev

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

apt-get install mariadb-server mariadb-client libmariadb-dev

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
cd /opt/eprints3/
git checkout tags/v3.4.6

==== 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
cd /opt/eprints3/
git checkout tags/v3.3.16

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

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

Then put in the source code in place:

mv eprints-3.4.6 /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/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6/flavours/pub_lib /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/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.6/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.6/

== 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 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

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

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

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

Installing EPrints on Debian/Ubuntu

2025-01-29T15:51:05Z

Alex-ball: In all six required OS versions, texlive-base-bin is a virtual package only provided by texlive-binaries.

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

== Requirements ==
* Ubuntu 20.04 LTS, 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 10 (Buster), Debian 11 (Bullseye) or Debian 12 (Bookworm) - 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 ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page.):

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-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl libdbd-mysql-perl python3-html2text make libexpat1-dev libxslt1-dev

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

apt-get install mysql-server mysql-client libmysqlclient-dev

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

apt-get install mariadb-server mariadb-client libmariadb-dev

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
cd /opt/eprints3/
git checkout tags/v3.4.6

==== 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
cd /opt/eprints3/
git checkout tags/v3.3.16

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

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

Then put in the source code in place:

mv eprints-3.4.6 /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/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6/flavours/pub_lib /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/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz -C /usr/share/eprints/
mv /usr/share/eprints/eprints-3.4.6/flavours /usr/share/eprints/
rmdir /usr/share/eprints/eprints-3.4.6/

== 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 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

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

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

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

Miscellaneous Config Options/get users owned eprints

2024-10-01T12:36:43Z

Alex-ball:

This example should work with v3.4.6+.

Prior to v3.4.6 defining this method resulted in unexpected behaviour when eprint_status checkboxes were used on the ''Manage deposits'' page.

== Example ==
$c->{get_users_owned_eprints} = sub
{
my( $session, $user, %opts ) = @_;
# for non-editorial accounts, return the normal list
if( $user->get_type ne "editor" )
{
return $user->owned_eprints_list_actual( %opts );
}
# only interested in editor accounts now
# allow editors to see their items, and items from a specific userid e.g. 99999
my $extra_userid = 99999;
my $searchexp = $opts{dataset}->prepare_search( %opts );
$searchexp->add_field( $opts{dataset}->field( "userid" ), $user->id . " $extra_userid", "IN", "ANY" );
return $searchexp->perform_search;
};

Prior to v3.4.6, this function was passed a different set of parameters, thus search options had to be hard-coded:

# v3.4.5 and earlier
$c->{get_users_owned_eprints} = sub
{
my( $session, $user, $dataset ) = @_;
my $searchexp = $dataset->prepare_search(
# options go here
);
# Add fields to $searchexp here
return $searchexp->perform_search;
};

Miscellaneous Config Options/get users owned eprints

2024-10-01T12:27:17Z

Alex-ball:

This example should work with v3.4.6+.

Prior to v3.4.6 defining this method resulted in unexpected behaviour when eprint_status checkboxes were used on the ''Manage deposits'' page.

== Example ==
$c->{get_users_owned_eprints} = sub
{
my( $session, $user, %opts ) = @_;
# for non-editorial accounts, return the normal list
if( $user->get_type ne "editor" )
{
return $user->owned_eprints_list_actual( %opts );
}
# only interested in editor accounts now
# allow editors to see their items, and items from a specific userid e.g. 99999
my $extra_userid = 99999;
my $searchexp = $opts{dataset}->prepare_search( %opts );
$searchexp->add_field( $opts{dataset}->field( "userid" ), $user->id . " $extra_userid", "IN", "ANY" );
return $searchexp->perform_search;
};

Prior to v3.4.6, this function was passed a different set of parameters, thus search options had to be hard-coded:

# v3.4.5 and earlier
$c->{get_users_owned_eprints} = sub
{
my( $session, $user, $dataset ) = @_;
my $searchexp = new EPrints::Search(
session => $session,
dataset => $dataset,
# plus any other options
);
# Add fields to $searchexp here
return $searchexp->perform_search;
};

EPrints 3.4.3

2021-04-27T12:11:09Z

Alex-ball: Switch column headings to correct columns

== Release Notes ==
EPrints 3.4.3 is now available on [https://files.eprints.org/2551 files.eprints.org] and [https://github.com/eprints/eprints3.4/releases/tag/v3.4.3 GitHub].
* '''Zero codename:''' ''Snickerdoodle Sandstorm''
* '''Publications flavour codename:''' ''Banana Bread Rainbow''

=== New Dependencies ===
None. Check earlier dependencies for [[EPrints 3.4.2]] and before.

=== Changes Since 3.4.2 ===

==== New Functionality ====
* Provides function (<tt>EPrints::Utils::compare_version</tt>) for comparing EPrints software versions so plugins can choose to behave differently.
* Adds <tt>jquery</tt> EPrints 3.4 ingredient to allow JQuery resources to be incorporated if required by non-core EPrints functionality. Ingredient added but commented out in <tt>flavours/pub_lib/inc</tt>.
* Provides picker for date fields to reduce potential for human error.

==== Security and Privacy Improvements ====
* Makes JSON export respect value set for <tt>export_as_xml</tt> to avoid exporting unintended fields.
* Sets <tt>contact_email</tt> to not export by default for better GDPR compliance.
* Rate limits failed local login attempts for a particular user. Defaults to 10 failed login attempts in 10 minutes (using <tt>$c->{max_login_attempts}</tt> and <tt>$c->{lockout_minutes}</tt> configuration options).
* Rate limits new account requests. Defaults to 100 requests in a hour long period to avoid causing problems with planned mass sign up events. Configured using <tt>$c->{max_account_requests}</tt> and <tt>$c->{max_account_requests_minutes}</tt> options.
* Limits the maximum length of a password (default 200 characters) to prevent specific Denial-of-Service attacks.
* Modifies <code>latex</code> invocation to make more secure an ensure it rights to the correct output directory.
* Removes legacy <code>/cgi/latex2png</code> script to prevent Remote Code Execution (RCE) from [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-3342 CVE-2021-3342].
* Validates parameters passed to <code>/cgi/cal</code> script to protect against RCE and Cross Site Scripting (XSS) from [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26475 CVE-2021-26475] and [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26476 CVE-2021-26476].
* Validates <code>dataset</code> parameter passed to <code>/cgi/dataset_dictionary</code> to protect against XSS from [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26702 CVE-2021-26702].
* Validates parameters passed to <code>/cgi/history_search</code> to protect against the possibility of XSS and MySQL injection vulnerabilities, although none currently exploitable.
* Validates <code>verb</code> passed to <code>/cgi/toolbox/toolbox</code> to protect against RCE from [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26704 CVE-2021-26704].
* Allows <code>EPrints::XML::parse_string</code> to temporarily modify parser configuration to disable expanding of XML entities by the <code>/cgi/ajax/phrase</code> script to protect against [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26703 CVE-2021-26703].
* Ensure <code>eprints_lang</code> cookie explicitly sets <code>SameSite</code> attribute to <code>Lax</code> if HTTPS is not enabled or sets <code>secure</code> attribute to <code>1</code> if it is.
* Doubles (to 16) number of characters used for randomly generated password suggestions (e.g. for database user created by <code>epadmin</code>).

==== General Improvements ====
* Resolves all accessibility errors and most alerts (as reported by the [https://wave.webaim.org/ WAVE Web Accessibility Evaluation Tool]) for backend admin pages as listed in the [https://accessibility.eprints-hosting.org/accessibility/report.html Accessibility report].
* [[#Configuration URLs and Paths|Tidies up the use of configuration URLs and Paths]]
* Uses HTML class for <tt>Longtext_counter</tt> counter line and provides CSS to by default make this red and bold if the <tt>maxwords</tt> limit is exceeded.
* Allows full path or just subject name to be displayed for values set in subjects field by setting <tt>render_path</tt> attribute (true by default).
* Allows time between password reset requests to be configured (to a number of hours) rather than hard-coded to 24 hours.
* Adds option to set status of EPrints that should be checked by <tt>check_xapian</tt> script.
* Adds <tt>date_embargo_retained</tt> field to Documents to retain the embargo date after the embargo is lifted.
* Adds deprecation warning to indicate only LibXML library will be supported in future versions of EPrints. (Version for removal yet to be confirmed).
* Adds basic default citation for files.
* Adds validation for date fields to prevent invalid dates being set.
* Allows files to be stored to disk with generic filenames (i.e. <code><fileid>.bin</code>) rather than the upload filename that can cause retrieval problem by setting the <code>$c->{generic_filenames}</code> configuration setting.
* Adds code to <code>lib</code> and <code>pub_lib</code> versions of <code>security.pl</code> to deal with request a copy access issue if repository has coversheets plugin enabled.
* Allows sub-fields to have help texts configured.
* Generates log message for views that have reached their <code>max_items</code> limit.
* Allows document fields displayed in an eprint's Details tab to be configured.
* Adds data-context attributes to aid CSS styling of HTML div elements within search forms.
* Improves scaling of of Lightbox popups on narrow screens.
* Allows a pin to set the id or class attribute for a template HTML element to facilitate different CSS styling on different pages.
* Prompts for organisation name when creating a new archive using <code>epadmin create</code>.
* Allows classes to be assigned to parts (i.e. top, left, main, after, etc.) of abstract/summary pages to facilitate better CSS styling.
* Allows search results forms to be configured to automatically reload on ordering change.
* Allows classes for EPrints' user menu (i.e. by default <code>ep_tm_key_tools</code>) to be configured to better integrate with institutional branding.
* Adds commented advice on fixing issues with PDF thumbnail generation using ImageMagick.
* Tidies up citations by removing identical <code>flavours/pub_lib/</code> citations that appear in <code>lib/</code>.
* Allows <code>max_files</code> that can be expanded from an uploaded zip file to be configured. (Previously hardcoded to 100 file limit).
* Allows customisable overriding of type-mapping based on <code>ispublished</code> value for BiBTeX and RIS export. (I.e. not using <code>@unpublished</code> type if <code>ispublished</code> set to <code>unpub</code>).
* Provides <code>has_role</code> EPC function to allow more granular control of workflows that can be edited by specific group of user that have has this role added to their profile.
* Allows positioning of hovering document preview to be set to left or right and implements this in <code>summary_page</code> and <code>result</code> eprint citations to improve preview positioning.
* Improves verbosity of <code>get_input</code> and <code>get_input_hidden</code> to explain better why input is invalid. Assisting <code>epadmin</code> data entry.
* Makes <code>id_number</code> (i.e. for DOIs, etc.) field default type <code>id</code> rather than <code>text</code> to facilitate search for exact IDs, especially those containing non-alphanumeric characters (e.g. 10.1016/j.ejor.2018.02.047).
* Restricts characters that can be used in new user-added subject IDs to alphanumeric characters, underscores and hyphens.
* Ensures subject-type field behaves the same in default (i.e. multiple select form element) as it does in subject tree format. I.e. subject tree mode lets previously selected subjects stay selected, even if the subject itself has been set as undepositable in the intervening period. Default mode silently unselects these.
* Switches to using real ''bazaar'' ingredient rather than ''bazaar_stub'' for zero flavour in <code>EPrints::SystemSettings</code> as this former is now available in core codebase.
* Prevents removing items that have and have once been in the live archive, without an extra permission: <code>eprints/remove_once_archived</code>. (Retiring items is still permitted without extra permission).

==== Bug Fixes ====
* Prevents access code from changing if request a copy is approved multiple times (and warns if request has already been approved).
* Fixes bug with logged in users not being able to access approved request a copy documents that they would not normally have access.
* Fixes formatting of results from user search introduced by accessibility changes in 3.4.2.
* Updates issue citation to use <code><div></code> rather than <code><tr></code> and <code><td></code> tags so it works with accessibility changes introduced in 3.4.2.
* Deals more gracefully if History DataObj's parent does not exist when checking if it is an <code>EPrints::List</code>.
* Fixes internal server error when trying to save values to a non-multiple compound field.
* Fixes issue with XML import setting unset compound subfields to NULL rather than empty string.
* Fixes errors on import pages caused by Accessibility improvements and fixes other Accessibility issues for import pages.
* Fixes broken link of default 401 error page.
* Sets STDOUT and STDERR binmode to utf8 to avoid wide character errors.
* Fixes user history layout as a result of earlier Accessibility improvements.
* Fixes missing phrases reported in error logs. Typically fieldhelp phrases for sub-fields of compound fields, which are generally not rendered but still report missing phrase warnings.
* Sets <code>SameSite</code> property to <code>None</code> for secure login and request copy cookies as Google Chrome is now quite strict about this.
* Provides handling for XML parsing of revision files to show warning for particular revision in the hostory tab rather than an internal server error for the whole page.
* Allows use of same pin multiple times within a phrase.
* Prevents undefined <code>$c->{aliases}</code> from causing <code>epadmin config_core</code> to fail.
* Ensures saved searches indicate email notifications cannot be sent when the <code>Xapianv2</code> (in addition to <code>Xapian</code>) plugin has been used for the original search.
* Adds missing <code>event_queue</code> phrases.
* Fixes inappropriate mapping of <code>monograph_type</code> in BibTeX import.
* Fixes erroneous post-login redirection when login required to access eprint summary/abstract pages and long URLs (e.g. /id/eprint/1234) enabled.
* Ensures <code>readonly</code> attribute works for <code>MetaField::Set</code> in compound-multiple fields.
* Adds missing <code>reason</code> phrase for <code>RejectWithEmail</code> screen plugin.
* Prevents HEAD requests (e.g. email link checkers) for password from resets from actioning the reset. (Otherwise, when the user clicks the link it will say the password has already been reset, which may concern the user).
* Forces full day-month-year to be set for document embargo expiry to avoid any ambiguity.
* Improves <code>epadmin</code> by removing unusable functionality and reporting if database tables do not get created as expected.
* Adds symlinks between <code>brief</code> and <code>default</code> citations for various data objects to prevent log warnings.
* Better handles DOI not being set when parsing it.
* Provides more useful logging when field has invalid parameters.
* Fixes missing pin for error message phrase when restarting indexer.
* Fixes <code>MetaField::Listing</code> from logging an error that no <code>datasetid</code> is defined when on its index page (listing datasets).
* Updates positions for plugins that appear in key tools menu to ensure deterministic ordering.
* Fixes bug to allow REST calls for subjects with IDs that contain full stops (.).
* Better handles finding parent eprint when this has been deleted.
* Fixes <code>tools/map_config.pl</code> to use correct directory for EPrints 3.4 and allow flavour to be specified as a parameter.
* Fixes <code>tools/update_phrase/file</code> to ensure EPrints libraries can be used and allows specified base path, current working directory or full path to be used for phrase file parameters.
* Fixes BibTeX import using uploaded files broken by update to third-party <code>BibTeX::Parser</code> in EPrints 3.4.2.
* Fixes RDF export by adding doi namespace for when id_number field is set to a DOI and is then translated to and owl:sameAs in a RDF export.
* Fixes bug preventing exporting file data objects in various metadata formats (e.g. Atom, EP3XML, CSV, etc.).

=== Known Issues ===
'''None at present.'''

=== Configuration URLs and Paths ===
EPrints has various configuration settings for URLs and paths that are automatically configured based on the settings in an archive's <code>cfg/cfg.d/10_core.pl</code>. The six most significant are the following:

; <code>http_url</code>
: The HTTP version of the URL (e.g. ''http://example.eprints.org''). Since EPrints 3.4.1, this will be set to the same as <code>https_url</code> if <code>$c->{host}</code> is undefined in the archive's ''cfg/cfg.d/10_core.pl''.
; <code>https_url</code>
: The HTTPS version of the URL (e.g. ''https://example.eprints.org''). If <code>$c->{securehost}</code> is not defined in the archive's <code>cfg/cfg.d/</code> directory (typically in <code>10_core.pl</code> or <code>https.pl</code>) then the URL will be set to HTTP (e.g. ''http://example.eprints.org'')
; <code>base_url</code>
: This is set to <code>http_url</code> or https_url</code> depending on whether <code>$c->{securehost}</code> is defined.
; <code>http_root</code>
: The HTTP version of the root path. Typically this will an empty string unless EPrints needs to run under its own path (e.g. ''http://example.eprints.org/eprints'' will need the <code>http_root</code> set to <code>/eprints</code>).
; <code>https_root</code>
: The HTTPS version of the root path. Typically this will be empty string unless EPrints needs to run under its own path (e.g. ''https://example.eprints.org/eprints'' will need the <code>https_root</code> set to ''/eprints'').
; <code>rel_path</code>
: Like <code>base_url</code> this is the same as the <code>http_root</code> or <code>https_root</code> dependent on whether <code>$c->{securehost}</code> is defined.

Each of the six configuration settings above have their sister configuration settings for their CGI URLs or paths:
{| class="wikitable"
|-
! Setting
! Example
! CGI Setting
! CGI Example
|-
| http_url
| http://example.eprints.org
| http_cgiurl
| http://example.eprints.org/cgi
|-
| https_url
| https://example.eprints.org
| https_cgiurl
| https://example.eprints.org/cgi
|-
| base_url
| https://example.eprints.org
| perl_url
| https://example.eprints.org/cgi
|-
| http_root
|
| http_cgiroot
| /cgi
|-
| https_root
|
| https_cgiroot
| /cgi
|-
| rel_path
|
| rel_cgipath
| /cgi
|}

Over time there has been a move from EPrints repositories being HTTP-only to HTTP and HTTPS and further towards HTTPS only (with HTTP redirects). EPrints configuration has had to evolve over time to support all these use cases, so those running EPrints can (continue to) run the HTTP/HTTPS setup that works for them. (Although, the recommendation would be to use the most secure configuration available). However, this has led to inconsistent use of the twelve configuration settings for URLs and paths described above. Therefore, EPrints 3.4.3 has attempted to tidy up much of this.

The use of <code>http_url</code>, <code>https_url</code>, <code>http_cgiurl</code> and <code>https_cgiurl</code> is unnecessary, when <code>base_url</code> and <code>perl_url</code> by default will consistently provide the most secure available option. (The only case where there may be issue is for URIs representing eprint items. Where changing the repository setup should not change permanent URIs. For this the recently introduced <code>uri_url</code> configuration option can be used). Using <code>base_url</code> and <code>perl_url</code> consistently also ensure that there is not switching between the use of HTTPS and HTTP. In particular, this helps avoid problems with the web browser reporting mixed content warnings (e.g. HTTP images on HTTPS pages) and warnings when forms are submitted to an HTTP URL and the current page is HTTPS.

Using a full URL (with a protcol and hostname) is excessive in most cases and therefore <code>rel_path</code> and <code>rel_cgipath</code> should be the preferred options. However, there are a number of situations where this would not be appropriate, as the URL may be used outside the scope of the EPrint repository:
# In export formats for eprint items
# In citations for eprint items
# In generated email messages
# Links in the web page head to related alternate resources of services independent of the web page (i.e. to export formats, API services but not CSS, JavaScript, favicons, etc.).
For all these scenarios not using a full URLs might prevent the resource being accessed once the content has been exported, embedded, emailed or consumed by a user or third-party application.

The use of <code>http_root</code>, <code>https_root</code>, <code>http_cgiroot</code> and <code>https_cgiroot</code> is also unnecessary, when <code>rel_path</code> and <code>rel_cgipath</code> are available. Except when being used to define other URL and path configuration settings or (with <code>http_url</code>) generating Apache configuration (using ''bin/generate_apacheconf'').

==== Summary of Changes ====
* All existing URL and path configuration settings have been retained to ensure existing plugins and bespoke code continue to function.
* Eliminated use of <code>http_url</code> (except in Apache configuration generation), <code>https_url</code>, <code>http_cgiurl</code> and <code>https_cgiurl</code>.
* Used <code>base_url</code> and <code>perl_url</code> for links related to user-generated content (i.e. eprint summary/abstract pages, document download URLs, document preview images/thumbnails, etc.), links defined in the head of a web page that are not directly related to the generation of the page (i.e. everything but CSS stylesheets, JavaScript and favicons) and links that are rendered as text on a web page.
* Used <code>rel_path</code> and <code>rel_cgipath</code> for all other purposes where it is unnecessary to use <code>base_url</code> or <code>perl_url</code>.
* Eliminated use of <code>http_cgiroot</code> and <code>https_cgiroot</code> and limited use of <code>http_root</code> and <code>https_root</code> to Apache configuration generation and in defining other configuration settings.
* Ensured <code>rel_path</code> and <code>rel_cgipath</code> are used for links in templates, static pages and other places where previously no URL/path configuration setting was used. To ensure these links work when EPrints is not running on the root path (i.e. <code>rel_path</code> is not an empty string).

== Planned Development ==
See [[EPrints 3.4.4]]

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

Archives/ARCHIVEID/cfg/templates/

2020-07-10T11:13:24Z

Alex-ball: Created page with "{{dirs}} *'''eprints3/archives/EPrints_Directory_Structure/eprints3/archives/ARCHI..."

{{dirs}}
*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/archives|archives]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID|ARCHIVEID]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|cfg]]/templates'''
** '''default.xml''' - Template used by some plugins to render web pages for this repository
** '''default_internal.xml''' - Fallback template to use to render web pages for this repository; usually symlinked to default.xml (New in EPrints 3.4)
** '''mainonlycss.xml''' - Additional template for very simple pages (no headers or footers, just the page title and content)

The files here are used for any language which does not have a more specific template installed in, say, [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/templates|eprints3/archives/ARCHIVEID/cfg/lang/en/templates/]] (for English-language pages).

This directory does not exist in a fresh installation. You have to create it yourself to override the files in [[EPrints_Directory_Structure/eprints3/lib/templates|eprints3/lib/templates/]].

EPrints Directory Structure/eprints3/archives/ARCHIVEID/cfg/templates

2020-07-10T11:07:19Z

Alex-ball: Redirected page to Archives/ARCHIVEID/cfg/templates/

#REDIRECT [[Archives/ARCHIVEID/cfg/templates/]]

EPrints Directory Structure/eprints3/lib/templates

2020-07-10T11:04:52Z

Alex-ball: Redirected page to Lib/templates/

#REDIRECT [[Lib/templates/]]

EPrints Directory Structure/eprints3/lib/templates

2020-07-10T11:04:30Z

Alex-ball: Redirected page to Lib/templates

#REDIRECT [[Lib/templates]]

Lib/templates/

2020-07-10T11:01:51Z

Alex-ball: Created page with "{{dirs}} {{noeditdir}} *'''eprints3/lib/templates''' ** '''default.xml''' - Template used..."

{{dirs}}
{{noeditdir}}
*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/lib|lib]]/templates'''
** '''default.xml''' - Template used by some plugins to render web pages for all repositories and languages
** '''default_internal.xml''' - Fallback template to use to render web pages for all repositories and languages; usually symlinked to default.xml (New in EPrints 3.4)
** '''mainonlycss.xml''' - Additional template for very simple pages (no headers or footers, just the page title and content)

These files are overridden if files with the same name exist in the following locations:

* [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/templates|eprints3/archives/ARCHIVEID/cfg/templates/]] (any language)
* [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/templates|eprints3/archives/ARCHIVEID/cfg/lang/en/templates/]] and similar (language-specific)

Archives/ARCHIVEID/cfg/lang/en/templates/

2020-07-10T10:54:50Z

Alex-ball: Update for EPrints 3.4

{{dirs}}
*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/archives|archives]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID|ARCHIVEID]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|cfg]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang|lang]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en|en]]/templates'''
** '''default.xml''' - Template used by some plugins to render web pages for this repository
** '''default_internal.xml''' - Fallback template to use to render web pages for this repository; usually symlinked to default.xml (New in EPrints 3.4)
** '''mainonlycss.xml''' - Additional template for very simple pages (no headers or footers, just the page title and content)

The files here are only used when rendering pages in English. To use the same template across all languages, put the files in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/templates|eprints3/archives/ARCHIVEID/cfg/templates/]] instead.

This directory does not exist in a fresh installation. You have to create it yourself to override the files in [[EPrints_Directory_Structure/eprints3/lib/templates|eprints3/lib/templates/]].

How to modify static pages

2020-07-10T10:29:39Z

Alex-ball: Clarify location of template

[[Category:Static Pages]]
The static web pages are created by combining the .xpage files from [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static | /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/static/]] with the site template; this is what generate_static does. A custom site template can be installed at [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/templates|opt/eprints3/archives/ARCHIVEID/cfg/lang/en/templates/]] (if language-specific) or [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/templates|opt/eprints3/archives/ARCHIVEID/cfg/templates/]] (if not); otherwise the default one at [[EPrints_Directory_Structure/eprints3/lib/templates|opt/eprints3/lib/templates/]] will be used.

The generate_static script also copies all files which do not have the suffix .xpage from [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static | /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/static/]]

Non-language specific files go in the [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static|/opt/eprints3/archives/ARCHIVEID/cfg/static/]] directory and appear on the website no matter what language the site is in, e.g. images and the style sheet.

Obviously cfg/lang/en/ is intended for English language source files; French source files would go in cfg/lang/fr/ and so on.

# Edit the .xpage file (or other file in /static/)
# Run [[Bin/|generate_static]] ARCHIVEID

===Issues===

The XML Editor encodes all extended characters, with the exception of core HTML ones (e.g. <) -- this causes issues with pages that need to include one of these symbols. See https://github.com/eprints/eprints/blob/3.3/perl_lib/EPrints/Plugin/Screen/Admin/Config/Edit/XML.pm#L29

A set of phrases have been created for html entites to be used in static pages and phrases that can be edited through the front-end tools. E.g:

<source lang='html4strict'>
<p>Nuts <epc:phrase ref='entity_amp'/> bolts</p>
</source>

A [http://bazaar.eprints.org/id/eprint/471 bazaar package] has been created for the following phrases:

* entity_amp
* entity_gt
* entity_lt
* entity_quot
* entity_apos

See http://bazaar.eprints.org/471/

Archives/ARCHIVEID/cfg/static/

2020-07-10T10:09:32Z

Alex-ball: Fix link

{{dirs}}
This directory represents the language-neutral top level of your website. Langauge specific files are in
[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static|eprints3/archives/ARCHIVEID/cfg/lang/en/static/]] (well, English ones are).

Files in this directory override files in [[EPrints Directory Structure/eprints3/lib/static|eprints3/lib/static/]].

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/archives|archives]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID|ARCHIVEID]]/[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|cfg]]/static'''
** '''[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static/images|images/]]''' - images
** '''[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static/javascript|javascript/]]''' - javascript scripts
** '''[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static/style|style/]]''' - css and style-related images

How to modify static pages

2020-07-10T10:04:53Z

Alex-ball: Fix location of templates and non-language specific files

[[Category:Static Pages]]
The static web pages are created by combining the .xpage files from [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static | /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/static/]] with the site template. The template can be found at [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/templates|opt/eprints3/archives/ARCHIVEID/cfg/templates/]]. This is what generate_static does.

Generate static also copies all files which do not have the suffix .xpage from [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static | /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/static/]]

Non-language specific files go in the [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static|/opt/eprints3/archives/ARCHIVEID/cfg/static/]] directory and appear on the website no matter what language the site is in. eg. images and the style sheet.

Obviously french source files go in cfg/lang/fr/ etc.

Edit the .xpage file (or other file in /static/)

Run [[Bin/|generate_static]] ARCHIVEID

===Issues===

The XML Editor encodes all extended characters, with the exception of core HTML ones (e.g. <) -- this causes issues with pages that need to include one of these symbols. See https://github.com/eprints/eprints/blob/3.3/perl_lib/EPrints/Plugin/Screen/Admin/Config/Edit/XML.pm#L29

A set of phrases have been created for html entites to be used in static pages and phrases that can be edited through the front-end tools. E.g:

<source lang='html4strict'>
<p>Nuts <epc:phrase ref='entity_amp'/> bolts</p>
</source>

A [http://bazaar.eprints.org/id/eprint/471 bazaar package] has been created for the following phrases:

* entity_amp
* entity_gt
* entity_lt
* entity_quot
* entity_apos

See http://bazaar.eprints.org/471/