EPrints Documentation - User contributions [en-gb]

Installing EPrints on Debian/Ubuntu

2026-05-27T09:35:10Z

Th.lauke@arcor.de: Debian versions continued, wget installation simplified

{{manual}}
[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 11 (Bullseye), Debian 12 (Bookworm) or Debian 13 (Trixie) - These are not as comprehensively tested as Ubuntu LTS versions.

=== 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 install perl libncurses6 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 install mysql-server mysql-client libmysqlclient-dev

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

apt install mariadb-server mariadb-client libmariadb-dev

Next, create the eprints user

adduser eprints

Now add the eprints user to the www-data group and vice-versa

usermod -a -G eprints www-data
usermod -a -G www-data 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.7

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

cd /tmp/
wget https://files.eprints.org/3288/1/eprints-3.4.7.tar.gz
tar xzvf eprints-3.4.7.tar.gz

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/3288/2/eprints-3.4.7-flavours.tar.gz
tar xzvf eprints-3.4.7-flavours.tar.gz

Then put in the prepared source code in place:

mv eprints-3.4.7 /opt/eprints3
chmod 2775 /opt/eprints3
chmod -R g+w /opt/eprints3/flavours/pub_lib
chown -R eprints:eprints /opt/eprints3

== 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>, if it does not already exist.

<code>EPRINTS_PATH</code> should now always be <code>/opt/eprints3</code>. However, historically other paths have been used when EPrints was available as a Deb package.

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:

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

== Operating System Version Specific Requirements ==

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

Upgrading between EPrints 3.4 versions

2025-02-28T14:28:37Z

Th.lauke@arcor.de: check of configuration files added

[[Category:Upgrading]]
This page is intended to provide guidance for those upgrading between versions of EPrints 3.4. (e.g. 3.4.1 to 3.4.2). This is generally intended for those upgrading using source tarballs available on [https://files.eprints.org/ files.eprints.org] or upgrading tagged release from [https://github.com/eprints/eprints3.4/ EPrints 3.4 GitHub repository]. However, '''new versions of EPrints 3.4 will no longer be released as Linux packages''' (i.e. [http://rpm.eprints.org/eprints3.4 RPMs] or [http://deb.eprints.org/3.4 Debs]).

== General Advice ==
If you are running EPrints as a virtual machine, then it is worthwhile taking a snapshot that you could revert back to this in the event of an unsuccessful upgrade. Otherwise, you should take the following backups before starting an upgrade:
; The EPrints database
: This will likely have the same name as the archive.
; The documents directory
: This is the ''documents'' directory, directly under the archive's directory (i.e. ''/opt/eprints3/archives/<ARCHIVE_NAME>/'').
; The Xapian index
: This is in the ''var'' directory of the archive under the directory named or starting ''xapian''.
; Your EPrints archive
: All the directories and any files in your archive, '''except''': ''documents'' (see above), ''html'' and ''var'' ('''except''' ''xapian'', see above). If you have multiple archives be sure to backup each one.
; The current EPrints codebase
: In case any changes have been made to this. These may be needed if you have to rollback an upgrade or also apply these changes if they are needed in the upgraded version of EPrints. All directories in the EPrints path (e.g. /opt/eprints3/) should be backed up '''except''': ''archives'' (see above), ''debian'', ''license'', ''pod'', ''testdata'', ''tests'',''tmp'' and ''var''. No files in the top level EPrints path directory need to be backed up.

Again, if you have the ability to take a virtual machine snapshot of your EPrints repository, it is worth using this to produce a clone, (if you do not already have a test or pre-production server version of your EPrints repository). This will allow you to check if you will have any snags either with the upgrade process or with the upgraded repository itself. It should also allow you to refine your upgrade schedule for your live EPrints repository to reduce the amount of scheduled downtime required.

== Upgrade Schedules ==
It would be expected that you have scheduled downtime (at least a day) and ideally try out the upgrade schedule on a cloned instance of your EPrints repository. If you tested the upgrade schedule on a clone, actual downtime (or more accurately at-risk period) will probably be less than an hour.

=== From a source tarball ===
1. Download the source tarball for both your current version of EPrints (e.g. 3.4.1) and your intended new version (e.g. 3.4.3) from [https://files.eprints.org/ files.eprints.org] and unpack into a separate directory on your EPrints repository server. E.g.
tar -xzvf eprints-3.4.1.tar.gz /home/eprints/
tar -xzvf eprints-3.4.1-flavours.tar.gz /home/eprints/
tar -xzvf eprints-3.4.3.tar.gz /home/eprints/
tar -xzvf eprints-3.4.3-flavours.tar.gz /home/eprints/

2. Compare the code to see if any critical changes have been made to the core codebase:
diff -x archives -x cfg -x tmp -rq /opt/eprints3 /home/eprints/eprints-3.4.1 | grep -v "/$ingredients\|var$"
Depending on your level of customization you should also pay attention to the results of
diff -rq /home/eprints/eprints3.4.3/flavours/pub_lib/defaultcfg/ /home/eprints/eprints3.4.1/flavours/pub_lib/defaultcfg/
or the equivalent command for the other flavours, or for a Zero EPrints repository
diff -rq /home/eprints/eprints3.4.3/lib/defaultcfg_zero /home/eprints/eprints3.4.1/lib/defaultcfg_zero
and even
diff -rq /home/eprints/eprints3.4.3/flavours/pub_lib/cfg.d/ /home/eprints/eprints3.4.1/flavours/pub_lib/cfg.d/
diff -rq /home/eprints/eprints3.4.3/lib/cfg.d/ /home/eprints/eprints3.4.1/lib/cfg.d/
diff -rq /home/eprints/eprints3.4.3/lib/syscfg.d/ /home/eprints/eprints3.4.1/lib/syscfg.d/
One of the first two directories was used for the initial configuration of your archive, and the latters control your repository by default; each of them could be overridden by your customized versions ...
Decide whether any personal version is still necessary, or meanwhile obsolete!

3. If there are any changes check to see if the change is present in the new version of EPrints. E.g.:
diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.1/flavours/pub_lib/inc
diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.3/flavours/pub_lib/inc
If the files in <Code>/opt/eprints3/</Code> are the same as that in the latest version (e.g. <Code>/home/eprints-3.4.3/</Code>) then no change is required. If some are not present in the latest version you need to consider whether they can/should be copied across (e.g. into <Code>/home/eprints/eprints-3.4.3/flavours/pub_lib/inc</Code>). It is likely new ingredients will be added to a flavours inc file between versions, so this file is particular important to check so your repository's local modifications to this file and modifications in the latest version of EPrints can be reconciled.

4. If your repository has any Bazaar plug-ins installed go to the Eprints Bazaar page on your repository via the Admin menu and download each one individually from the ''Developer Tools'' tab.

5. Stop the webserver and EPrints indexer on your repository server and check they have stopped running:
systemctl stop httpd
ps aux | grep httpd
/opt/eprints3/bin/indexer stop
ps aux | grep indexer
''httpd'' is for RHEL-based Linux OS, for Debian-based Linux OS use ''apache2''.

6. As root, move the new version of EPrints (with any ported changes, from step 3) to <Code>/opt/eprints3-new</code>
mv /home/eprints-3.4.3 /opt/eprints3-new

7. As the eprints user move the contents of the current archives into the new directory:
mv /opt/eprints3/archives/* /opt/eprints3-new/archives/
If <Code>/opt/eprints3/archives</Code> or any of its archives are on a different disk partition, this may take a long time and the partition you are moving it to may not be big enough. It may be better to figure out an alternative way of updating the other EPrints directories without moving the archive between disk partitions and then switching round the eprints directories (step 9 below).

8. As the eprints user copy across ingredients ('''except''' the bazaar and jquery ingredient) to the new version:
rsync -a --exclude=bazaar --exclude=jquery /opt/eprints3/ingredients/ /opt/eprints3-new/ingredients/

9. As root, switch round the old and new eprints directories:
mv /opt/eprints3 /opt/eprints3-old
mv /opt/eprints3-new /opt/eprints3

10. As the eprints user, test EPrints is in a good state:
/opt/eprints3/bin/epadmin test
If you have various Bazaar plug-ins installed, it is likely that this will report issues. If so you will need to disable these files until you can re-install the Bazaar plug-ins. E.g.
cd /opt/eprints3/archives/<ARCHIVE_NAME>/cfg/cfg.d/
rm ../epm/*
mv z_orcid_support.pl z_orcid_support.pl.disabled
mv zz_hefce_oa_fields.pl zz_hefce_oa_fields.pl.disabled
mv zz_rioxx2.pl zz_rioxx2.pl.disabled
mv z_meprints.pl z_meprints.pl.disabled
mv kultur.pl kultur.pl.disabled

11. Assuming EPrints is (now) in a good state, regenerate EPrints' Apache configuration:
/opt/eprints3/bin/generate_apacheconf --system --replace

12. As root, check the Apache configuration is sound and restart the webserver:
apachectl configtest
systemctl start httpd
For Debian-based LinuxOS use:
apache2ctl configtest
systemctl start apache2

13. Load up your repository in a web browser, login and go to the EPrints Bazaar page via the Admin menu. Install all the Bazaar plug-ins you downloaded in step 4. You can do this by scrolling to the bottom of the ''Available'' tab and using the ''Upload and Install'' section. Once you have re-installed all the Bazaar plug-ins, you can move back all the files you disabled in step 10. Then use ''epadmin'' to re-test and restart the webserver:
/opt/eprints3/bin/epadmin test
systemctl start httpd

14. Now using your web browser do a thorough test of both the functionality and the appearance/layout of your repository and make tweaks to your local archive configuration as necessary (e.g. modify the CSS).

13. Finally, as the eprints user, restart the indexer.
/opt/eprints3/bin/indexer start

It is advised that you keep the <Code>/opt/eprints3-old</Code> directory for a while (at least a month) in case you spot any unexpected problems. Worse case scenario you can revert back to this version by doing steps 7 and 9 in reverse. However, typically it is useful as a reference if you forgot to port a bespoke core code change of your old version of EPrints or a change you did port does not work as expected.

=== From GitHub release ===
'''N.B. These instructions are a work in progress.'''

Before staring check that no critical files have been modified in the core codebase.
cd /opt/eprints3/
git status
The only file that should have been modified (assuming you are running a publications flavour of EPrints) is ''flavours/pub_lib/inc''.

There may be various new directories/files under the ''lib'' and ''ingredients'' directories. These will most likely have been created as a result of installing Bazaar plug-ins or EPrints ingredients. You should make a note of these and check to see that they are present after the upgrade schedule has been completed.

If there are modified files (according to ''git status''), you should similarly make a note of these and the changes made, so it can be checked if either these changes have already been applied in the upgraded versions of these files or that they need to be re-applied after upgrading.

If ''git status'' finds missing files, then similarly these should be checked to make sure they are not present after completing your upgrade and remove them if they still exist. They were most likely removed to deliberately disable a piece of unwanted functionality. Although generally it should be possible to disable this with configuration.

If only the flavour's inc file is modified and the only other things ''git status'' shows are additional untracked files, then it is safe to do an '''In-place Upgrade'''. Otherwise, you will want to do a '''Clean Upgrade'''.

==== In-place Upgrade ====
All steps should be done as the eprints users, although some commands may prompt for a root password.

1. Stop the webserver and EPrints indexer.
apachectl graceful-stop
/opt/eprints3/bin/indexer stop

2. Make a copy of the flavour's inc file:
cp /opt/eprints3/flavours/FLAVOUR_lib/inc /home/eprints/inc.backup

3. Get the latest code version. This can be done with the following commands (substituting X for the latest version):
git fetch
git checkout v3.4.X

4. Check if the flavour's inc file has been reverted, if it is move back the backup to re-update it
mv /home/eprints/inc.backup /opt/eprints3/flavours/FLAVOUR_lib/inc

5. Test the new configuration and fix ans issues reported.
/opt/eprints3/bin/epadmin test

6. Update the database schema for any changes between versions
/opt/eprints3/bin/epadmin upgrade ARCHIVEID

7. Regenerate the EPrints Apache configuration, just in case there have been any improvements to this in the new version:
/opt/eprints3/bin/generate_apacheconf --system --replace

8. Start the webserver and EPrints Indexer
apachectl start
/opt/eprints3/bin/indexer start

==== Clean Upgrade ====
Step 1 needs to be done as the root. Steps 2 and onwards should be done as the eprints users, although some commands may prompt for a root password.

1. Create a new directory for latest version of eprints (substituting X for the latest version):
mkdir /opt/eprints3.4.X
chmod 2775 /opt/eprints3.4.X
chown eprints:eprints /opt/eprints3.4.X

2. Clone the latest released version of EPrints 3.4 (again substituting X for the latest version):
git clone https://github.com/eprints/eprints3.4 /opt/eprints3.4.X
cd /opt/eprints3.4.X
git checkout v3.4.X

3a. If you are not using the ''flavours/pub_lib'' copy the flavour library across (substituting ''FLAVOUR_LIB'' and ''X'' as appropriate):
cp -rf /opt/eprints3/flavours/FLAVOUR_LIB/ /opt/eprints3.4.X/flavours/

3b. If you are using ''flavours/pub_lib'' just copy over the ''inc'' file to the newly checked out ''pub_lib'' (again substituting ''X'' as appropriate):
cp /opt/eprints3/flavours/pub_lib/inc /opt/eprints3.4.X/flavours/pub_lib/

4. Review any modified tracked files by comparing these with the new version of the file in /opt/eprints3.4.X/. If the change is present in the new version then this change can be ignored, if it is not you may need to figure out how to incorporate this change into the new version of EPrints.

5. Copy across any additional untracked files from <code>/opt/eprints3/</code> to <code>/opt/eprints3.4.X/</code>. These will likely be either ingredients or separate files installed as part of a Bazaar plug-in.

6. Stop the EPrints indexer and webserver:
/opt/eprints3/bin/indexer stop
apachectl graceful-stop

7. Move around the old and new eprints directories and then move the archive directory across to the newly created archives sub-directory (substituting ''X'' and ''ARCHIVEID'' as appropriate):
mv /opt/eprints3 /opt/eprints3.old
mv /opt/eprints3.4.X /opt/eprints3
mv /opt/eprints3.old/archives/ARCHIVEID /opt/eprints3/archives/

8. Test the new configuration and fix any issues reported.
/opt/eprints3/bin/epadmin test

9. Update the database schema for any changes between versions
/opt/eprints3/bin/epadmin upgrade ARCHIVEID

10. Regenerate the EPrints Apache configuration:
/opt/eprints3/bin/generate_apacheconf --system --replace

11. Start the webserver and EPrints Indexer
apachectl start
/opt/eprints3/bin/indexer start

Cgi/users/lookup/

2025-02-26T18:32:01Z

Th.lauke@arcor.de: typo removed

{{dirs}}

These are scripts used by the autocomplete system in the workflow.

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/cgi|cgi]]/[[EPrints_Directory_Structure/eprints3/cgi/users|users]]/lookup'''
** '''event_by_name''' - Can only be linked from the event_name field. Looks up existing events with the same name and suggests them filling in other parts of the even data such as dates, location and type.
** '''file''' - This uses a file in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/autocomplete|eprints3/archives/ARCHIVEID/cfg/autocomplete/]]. The name of the file is specified in the CGI param "file". The format of the file is a set of lines. Each line contains a lookup string, a tab, and a chunk of XML. This XML is a single autocomplete block.
** '''journal_by_issn''' - Lookup journal details (issn, name, publisher) from the issn field. Looks at only records already in the repository.
** '''journal_by_name''' - Lookup journal details (issn, name, publisher) from the journal title field. Looks at only records already in the repository.
** '''name''' - Lookup the name of creators (and their email), uses existing creators.
** '''simple_file''' - As with "file" above, but just contains a list of lookup values, one of which may be selected to populate the current field only.
** '''simple_sql''' - As with SQL (see below), but just uses the "value" field to populate the current field only.
** '''sql''' - Similar to file, but uses an SQL table to do the lookup. The table is specified by the CGI param "title" but will be prefixed with "ac_". So a title param of "badger" would lookup in table "ac_badger". This table must contain a column titled "value" containing lookup terms and a column titled "xml" containing an XML autocomplete block.
** '''title_duplicates''' - This works only on the "title" field and warns of duplicates, rather than offering completion.

The '''file''', '''simple_file''', '''sql''' and '''simple_sql''' scripts may take a second CGI parameter, "mode". This may be set to "phrase" or "prefix". "phrase" is the default, and searches for the partial string anywhere within the lookup value. If set to "prefix" then this only matches starting at the start of the lookup value. This is primarily useful for large SQL tables, if you've added an index to the "value" field.

You can drop your own custom scripts into this directory, but you shouldn't if you do ''not'' want to lose your file with the next update: As usually it's advised to put it into <code>repoID/cgi</code>, <code>cfg/cgi</code> or even <code>site_lib/cgi</code>, depending on the intended scope respectively.

Cgi/users/lookup/

2025-02-26T18:30:37Z

Th.lauke@arcor.de: typos removed, advice and formatting added

{{dirs}}

These are scripts used by the autocomplete system in the workflow.

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/cgi|cgi]]/[[EPrints_Directory_Structure/eprints3/cgi/users|users]]/lookup'''
** '''event_by_name''' - Can only be linked from the event_name field. Looks up existing events with the same name and suggests them filling in other parts of the even data such as dates, location and type.
** '''file''' - This uses a file in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/autocomplete|eprints3/archives/ARCHIVEID/cfg/autocomplete/]]. The name of the file is specified in the CGI param "file". The format of the file is a set of lines. Each line contains a lookup string, a tab, and a chunk of XML. This XML is a single autocomplete block.
** '''journal_by_issn''' - Lookup journal details (issn, name, publisher) from the issn field. Looks at only records already in the repository.
** '''journal_by_name''' - Lookup journal details (issn, name, publisher) from the journal title field. Looks at only records already in the repository.
** '''name''' - Lookup the name of creators (and their email), uses existing creators.
** '''simple_file''' - As with "file" above, but just contains a list of lookup values, one of which may be selected to populate the current field only.
** '''simple_sql''' - As with SQL (see below), but just uses the "value" field to populate the current field only.
** '''sql''' - Similar to file, but uses an SQL table to do the lookup. The table is specified by the CGI param "title" but will be prefixed with "ac_". So a title param of "badger" would lookup in table "ac_badger". This table must contain a column titled "value" containing lookup terms and a column titled "xml" containing an XML autocomplete block.
** '''title_duplicates''' - This works only on the "title" field and warns of duplicates, rather than offering completion.

The '''file''', '''simple_file''', '''sql''' and '''simple_sql''' scripts may take a second CGI parameter, "mode". This may be set to "phrase" or "prefix". "phrase" is the default, and searches for the partial string anywhere within the lookup value. If set to "prefix" then this only matches starting at the start of the lookup value. This is primarily useful for large SQL tables, if you've added an index to the "value" field.

You can drop your own custom scripts into this directory, but you shouldn't if do not want to lose your file with the next update: As usually it's advised to put it into <code>repoID/cgi</code>, <code>cfg/cgi</code> or even <code>site_lib/cgi</code>, depending on the intended scope respectively.

Upgrading

2025-02-25T12:56:49Z

Th.lauke@arcor.de: category added

[[Category:Upgrading]]
{{manual}}
== Upgrade between same series versions of EPrints ==
If you are upgrading between the same series versions of EPrints (e.g. 3.3.15 to 3.3.16 or 3.4.2 to 3.4.3) then the upgrade process is somewhat more straightforward that upgrading between EPrints series versions (e.g. 3.3.16 to 3.4.3). This page was originally written for upgrading between 3.3 series versions, '''[[Upgrading between EPrints 3.4 versions]]''' provides additional specific information about EPrints 3.4 series.

=== From a Linux Package Manager ===
If you have installed from the Deb or RPM package, then you can just upgrade this. However, it is recommended that you have done a backup before doing this. Also if this is on a production server, that you do this during an extended period of scheduled downtime and have previously tested the upgrade on a pre-production server.

Once the package upgrade has completed make sure to run both ''epadmin upgrade'' and ''epadmin update'' on all archives. The package manager may only tell you need to run ''epadmin upgrade'' but ''epadmin update'' is also needed to ensure newly added fields to data objects are also incorporated.
/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID

=== From GitHub ===
If you have installed with GitHub, the preferred method for production repositories, you can update to the latest version using the following commands, substituting ''y'' for the version you want and ''x'' for the 3 or 4 depending on whether you are upgrading between EPrints 3.3 or 3.4 series:

git fetch origin
git merge tags/v3.x.y

This should warn you if you have made any locally uncommitted changes. You may need to use ''git stash'' to move these temporarily and reintegrate after updating from GitHub.

Once updated to the intended tagged release version any resolved and local uncommitted changes then make sure to run both ''epadmin upgrade'' and ''epadmin update'' on all archives and then reload the webserver and EPrints indexer, e.g.
/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID
apachectl graceful
/opt/eprints3/bin indexer restart

=== From a Tarball ===
Although not impossible it is strongly discouraged to upgrade from a tarball. One major reason not to do this is that if you have made any local changes other than to your original archive's configuration, it will be difficult to ensure all these modifications are retained. However, if you wish to do this, you can follow the instructions below, (as the eprints user unless otherwise stated):

==== Downloading and Unpacking 3.3 ====
<ol>
<li> Download the tarball from files.eprints.org, (e.g. https://files.eprints.org/2306/5/eprints-3.3.16.tar.gz)</li>

<li> As the root user, unpack the tarball under the same parent path as your existing EPrints and change the ownership of this whole directory structure</li>

cd /opt
tar -xzvf eprints-3.3.16.tar.gz
mv eprints-3.3.16 eprints3_new
chown -R eprints:eprints /opt/eprints3_new

</ol>
==== Downloading and Unpacking 3.4 ====
<ol>
<li> Download the main tarball from files.eprints.org, (e.g. https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz)</li>
<li> Download the publications tarball from files.eprints.org, (e.g. https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz)</li>
<li> As the root user, unpack the tarball under the same parent path as your existing EPrints and change the ownership of this whole directory structure</li>

cd /opt
tar -xzvf /home/eprints/eprints-3.4.6.tar.gz
tar -xzvf /home/eprints/eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6 eprints3_new
chown -R eprints:eprints /opt/eprints3_new

</ol>

==== Installing and Configuring ====

<ol>
<li> As the root user, stop Apache and EPrints' indexer.</li>

apachectl graceful-stop
/opt/eprints3/bin/epindexer stop

<li> Move the archive(s) from your old EPrints to your new one, e.g.</li>

mv /opt/eprints3/archives/* /opt/eprints3_new/archives/

<li> Copy SystemSettings.pm to your new EPrints as well as site-wide settings</li>

cp -p /opt/eprints3/perl_lib/EPrints/SystemSettings.pm /opt/eprints3_new/perl_lib/EPrints/
cp -pR /opt/eprints3/cfg /opt/eprints3_new/cfg
cp -pR /opt/eprints3/site_lib /opt/eprints3_new/site_lib

<li> If you are aware of any local modifications to files under your EPrints path (e.g. /opt/eprints3) but outside the archives directory then compare these files using diff to work out how your local changes can be integrated. E.g.</li>

diff /opt/eprints3/perl_lib/EPrints/MetaField/Date.pm /opt/eprints3_new/perl_lib/EPrints/MetaField/Date.pm

<li> As the root user, switch round the old and new versions of EPrints, e.g.</li>

mv /opt/eprints3 /opt/eprints3_old
mv /opt/eprints3_new /opt/eprints3

<li> Run epadmin test to check there are no configuration issues, e.g.</li>

/opt/eprints3/bin/epadmin test

<li> Run ''epadmin upgrade'' and ''epadmin update'' to deploy any structural changes or addition of fields to the database, e.g.</li>

/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID

<li> Restart EPrints' indexer.</li>

/opt/eprints3/bin/epindexer start

<li> As the root user, restart Apache.</li>

apachectl restart

<li>Don't forget to reinstall your Bazaar packages.</li>
</ol>

== Upgrading to EPrints to 3.3 ==
Upgrading from older 3.1 and 3.2 versions of EPrints to 3.3 is somewhat more involved. Please see the following guides:
* [[Upgrading from 3.1]]
* [[Upgrading from 3.2]]

== Upgrading to EPrints 3.4 ==
To upgrade to EPrints 3.4 you will need to already be running a version of EPrints 3.3. Ideally at least 3.3.12, which has the following guide:
* [[Upgrading 3.3.12+ to 3.4]]

Upgrading between EPrints 3.4 versions

2025-02-25T12:49:50Z

Th.lauke@arcor.de: typos removed, category added, some reformatting

[[Category:Upgrading]]
This page is intended to provide guidance for those upgrading between versions of EPrints 3.4. (e.g. 3.4.1 to 3.4.2). This is generally intended for those upgrading using source tarballs available on [https://files.eprints.org/ files.eprints.org] or upgrading tagged release from [https://github.com/eprints/eprints3.4/ EPrints 3.4 GitHub repository]. However, '''new versions of EPrints 3.4 will no longer be released as Linux packages''' (i.e. [http://rpm.eprints.org/eprints3.4 RPMs] or [http://deb.eprints.org/3.4 Debs]).

== General Advice ==
If you are running EPrints as a virtual machine, then it is worthwhile taking a snapshot that you could revert back to this in the event of an unsuccessful upgrade. Otherwise, you should take the following backups before starting an upgrade:
; The EPrints database
: This will likely have the same name as the archive.
; The documents directory
: This is the ''documents'' directory, directly under the archive's directory (i.e. ''/opt/eprints3/archives/<ARCHIVE_NAME>/'').
; The Xapian index
: This is in the ''var'' directory of the archive under the directory named or starting ''xapian''.
; Your EPrints archive
: All the directories and any files in your archive, '''except''': ''documents'' (see above), ''html'' and ''var'' ('''except''' ''xapian'', see above). If you have multiple archives be sure to backup each one.
; The current EPrints codebase
: In case any changes have been made to this. These may be needed if you have to rollback an upgrade or also apply these changes if they are needed in the upgraded version of EPrints. All directories in the EPrints path (e.g. /opt/eprints3/) should be backed up '''except''': ''archives'' (see above), ''debian'', ''license'', ''pod'', ''testdata'', ''tests'',''tmp'' and ''var''. No files in the top level EPrints path directory need to be backed up.

Again, if you have the ability to take a virtual machine snapshot of your EPrints repository, it is worth using this to produce a clone, (if you do not already have a test or pre-production server version of your EPrints repository). This will allow you to check if you will have any snags either with the upgrade process or with the upgraded repository itself. It should also allow you to refine your upgrade schedule for your live EPrints repository to reduce the amount of scheduled downtime required.

== Upgrade Schedules ==
It would be expected that you have scheduled downtime (at least a day) and ideally try out the upgrade schedule on a cloned instance of your EPrints repository. If you tested the upgrade schedule on a clone, actual downtime (or more accurately at-risk period) will probably be less than an hour.

=== From a source tarball ===
1. Download the source tarball for both your current version of EPrints (e.g. 3.4.1) and your intended new version (e.g. 3.4.3) from [https://files.eprints.org/ files.eprints.org] and unpack into a separate directory on your EPrints repository server. E.g.
tar -xzvf eprints-3.4.1.tar.gz /home/eprints/
tar -xzvf eprints-3.4.1-flavours.tar.gz /home/eprints/
tar -xzvf eprints-3.4.3.tar.gz /home/eprints/
tar -xzvf eprints-3.4.3-flavours.tar.gz /home/eprints/

2. Compare the code to see if any critical changes have been made to the core codebase:
diff -x archives -x cfg -x tmp -rq /opt/eprints3 /home/eprints/eprints-3.4.1 | grep -v "/$ingredients\|var$"

3. If there are any changes check to see if the change is present in the new version of EPrints. E.g.:
diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.1/flavours/pub_lib/inc
diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.3/flavours/pub_lib/inc
If the files in <Code>/opt/eprints3/</Code> are the same as that in the latest version (e.g. <Code>/home/eprints-3.4.3/</Code>) then no change is required. If some are not present in the latest version you need to consider whether they can/should be copied across (e.g. into <Code>/home/eprints/eprints-3.4.3/flavours/pub_lib/inc</Code>). It is likely new ingredients will be added to a flavours inc file between versions, so this file is particular important to check so your repository's local modifications to this file and modifications in the latest version of EPrints can be reconciled.

4. If your repository has any Bazaar plug-ins installed go to the Eprints Bazaar page on your repository via the Admin menu and download each one individually from the ''Developer Tools'' tab.

5. Stop the webserver and EPrints indexer on your repository server and check they have stopped running:
systemctl stop httpd
ps aux | grep httpd
/opt/eprints3/bin/indexer stop
ps aux | grep indexer
''httpd'' is for RHEL-based Linux OS, for Debian-based Linux OS use ''apache2''.

6. As root, move the new version of EPrints (with any ported changes, from step 3) to <Code>/opt/eprints3-new</code>
mv /home/eprints-3.4.3 /opt/eprints3-new

7. As the eprints user move the contents of the current archives into the new directory:
mv /opt/eprints3/archives/* /opt/eprints3-new/archives/
If <Code>/opt/eprints3/archives</Code> or any of its archives are on a different disk partition, this may take a long time and the partition you are moving it to may not be big enough. It may be better to figure out an alternative way of updating the other EPrints directories without moving the archive between disk partitions and then switching round the eprints directories (step 9 below).

8. As the eprints user copy across ingredients ('''except''' the bazaar and jquery ingredient) to the new version:
rsync -a --exclude=bazaar --exclude=jquery /opt/eprints3/ingredients/ /opt/eprints3-new/ingredients/

9. As root, switch round the old and new eprints directories:
mv /opt/eprints3 /opt/eprints3-old
mv /opt/eprints3-new /opt/eprints3

10. As the eprints user, test EPrints is in a good state:
/opt/eprints3/bin/epadmin test
If you have various Bazaar plug-ins installed, it is likely that this will report issues. If so you will need to disable these files until you can re-install the Bazaar plug-ins. E.g.
cd /opt/eprints3/archives/<ARCHIVE_NAME>/cfg/cfg.d/
rm ../epm/*
mv z_orcid_support.pl z_orcid_support.pl.disabled
mv zz_hefce_oa_fields.pl zz_hefce_oa_fields.pl.disabled
mv zz_rioxx2.pl zz_rioxx2.pl.disabled
mv z_meprints.pl z_meprints.pl.disabled
mv kultur.pl kultur.pl.disabled

11. Assuming EPrints is (now) in a good state, regenerate EPrints' Apache configuration:
/opt/eprints3/bin/generate_apacheconf --system --replace

12. As root, check the Apache configuration is sound and restart the webserver:
apachectl configtest
systemctl start httpd
For Debian-based LinuxOS use:
apache2ctl configtest
systemctl start apache2

13. Load up your repository in a web browser, login and go to the EPrints Bazaar page via the Admin menu. Install all the Bazaar plug-ins you downloaded in step 4. You can do this by scrolling to the bottom of the ''Available'' tab and using the ''Upload and Install'' section. Once you have re-installed all the Bazaar plug-ins, you can move back all the files you disabled in step 10. Then use ''epadmin'' to re-test and restart the webserver:
/opt/eprints3/bin/epadmin test
systemctl start httpd

14. Now using your web browser do a thorough test of both the functionality and the appearance/layout of your repository and make tweaks to your local archive configuration as necessary (e.g. modify the CSS).

13. Finally, as the eprints user, restart the indexer.
/opt/eprints3/bin/indexer start

It is advised that you keep the <Code>/opt/eprints3-old</Code> directory for a while (at least a month) in case you spot any unexpected problems. Worse case scenario you can revert back to this version by doing steps 7 and 9 in reverse. However, typically it is useful as a reference if you forgot to port a bespoke core code change of your old version of EPrints or a change you did port does not work as expected.

=== From GitHub release ===
'''N.B. These instructions are a work in progress.'''

Before staring check that no critical files have been modified in the core codebase.
cd /opt/eprints3/
git status
The only file that should have been modified (assuming you are running a publications flavour of EPrints) is ''flavours/pub_lib/inc''.

There may be various new directories/files under the ''lib'' and ''ingredients'' directories. These will most likely have been created as a result of installing Bazaar plug-ins or EPrints ingredients. You should make a note of these and check to see that they are present after the upgrade schedule has been completed.

If there are modified files (according to ''git status''), you should similarly make a note of these and the changes made, so it can be checked if either these changes have already been applied in the upgraded versions of these files or that they need to be re-applied after upgrading.

If ''git status'' finds missing files, then similarly these should be checked to make sure they are not present after completing your upgrade and remove them if they still exist. They were most likely removed to deliberately disable a piece of unwanted functionality. Although generally it should be possible to disable this with configuration.

If only the flavour's inc file is modified and the only other things ''git status'' shows are additional untracked files, then it is safe to do an '''In-place Upgrade'''. Otherwise, you will want to do a '''Clean Upgrade'''.

==== In-place Upgrade ====
All steps should be done as the eprints users, although some commands may prompt for a root password.

1. Stop the webserver and EPrints indexer.
apachectl graceful-stop
/opt/eprints3/bin/indexer stop

2. Make a copy of the flavour's inc file:
cp /opt/eprints3/flavours/FLAVOUR_lib/inc /home/eprints/inc.backup

3. Get the latest code version. This can be done with the following commands (substituting X for the latest version):
git fetch
git checkout v3.4.X

4. Check if the flavour's inc file has been reverted, if it is move back the backup to re-update it
mv /home/eprints/inc.backup /opt/eprints3/flavours/FLAVOUR_lib/inc

5. Test the new configuration and fix ans issues reported.
/opt/eprints3/bin/epadmin test

6. Update the database schema for any changes between versions
/opt/eprints3/bin/epadmin upgrade ARCHIVEID

7. Regenerate the EPrints Apache configuration, just in case there have been any improvements to this in the new version:
/opt/eprints3/bin/generate_apacheconf --system --replace

8. Start the webserver and EPrints Indexer
apachectl start
/opt/eprints3/bin/indexer start

==== Clean Upgrade ====
Step 1 needs to be done as the root. Steps 2 and onwards should be done as the eprints users, although some commands may prompt for a root password.

1. Create a new directory for latest version of eprints (substituting X for the latest version):
mkdir /opt/eprints3.4.X
chmod 2775 /opt/eprints3.4.X
chown eprints:eprints /opt/eprints3.4.X

2. Clone the latest released version of EPrints 3.4 (again substituting X for the latest version):
git clone https://github.com/eprints/eprints3.4 /opt/eprints3.4.X
cd /opt/eprints3.4.X
git checkout v3.4.X

3a. If you are not using the ''flavours/pub_lib'' copy the flavour library across (substituting ''FLAVOUR_LIB'' and ''X'' as appropriate):
cp -rf /opt/eprints3/flavours/FLAVOUR_LIB/ /opt/eprints3.4.X/flavours/

3b. If you are using ''flavours/pub_lib'' just copy over the ''inc'' file to the newly checked out ''pub_lib'' (again substituting ''X'' as appropriate):
cp /opt/eprints3/flavours/pub_lib/inc /opt/eprints3.4.X/flavours/pub_lib/

4. Review any modified tracked files by comparing these with the new version of the file in /opt/eprints3.4.X/. If the change is present in the new version then this change can be ignored, if it is not you may need to figure out how to incorporate this change into the new version of EPrints.

5. Copy across any additional untracked files from <code>/opt/eprints3/</code> to <code>/opt/eprints3.4.X/</code>. These will likely be either ingredients or separate files installed as part of a Bazaar plug-in.

6. Stop the EPrints indexer and webserver:
/opt/eprints3/bin/indexer stop
apachectl graceful-stop

7. Move around the old and new eprints directories and then move the archive directory across to the newly created archives sub-directory (substituting ''X'' and ''ARCHIVEID'' as appropriate):
mv /opt/eprints3 /opt/eprints3.old
mv /opt/eprints3.4.X /opt/eprints3
mv /opt/eprints3.old/archives/ARCHIVEID /opt/eprints3/archives/

8. Test the new configuration and fix any issues reported.
/opt/eprints3/bin/epadmin test

9. Update the database schema for any changes between versions
/opt/eprints3/bin/epadmin upgrade ARCHIVEID

10. Regenerate the EPrints Apache configuration:
/opt/eprints3/bin/generate_apacheconf --system --replace

11. Start the webserver and EPrints Indexer
apachectl start
/opt/eprints3/bin/indexer start

Frequently Asked Questions

2025-02-25T10:04:11Z

Th.lauke@arcor.de: typos removed

[[Category:FAQ]]
[[Category:Management]]
[[Category:Out of Date]]

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any Linux operating system. We use Ubuntu (Debian) and Redhat Enterprise Linux.

Running EPrints on Microsoft Windows is possible but strongly not recommended. It can be very difficult to get all the necessary dependencies in place. If you want to get EPrints running but do not have a computer running a Linux operating system, you could install [https://www.virtualbox.org/wiki/Downloads VirtualBox] and then create a Ubuntu or Redhat "virtual machine" (VM) to run on top of your Windows operating system. Alternatively, you could install [https://docs.docker.com/docker-for-windows/install/ Docker Desktop for Windows] and [[Installing EPrints using Docker|install EPrints using Docker]]. However, both these methods are only recommended for testing or demoing EPrints. If you intend to run EPrints long-term you should install on a dedicated Linux server or virtual machine.

== What computer do we need? ==
Any modern physical PC (server or desktop) or a virtual machine should be more than capable of running EPrints. A suggested minimum specification for running a live service:
* 2GB RAM
* 15GB disk space
* 100Mb/s network speed

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much disk space will we need? ==
The main usage of disk space will be the uploaded files for the publications, (e.g. PDF, Word documents, etc.). On average an eprint item will have associated files (e.g. uploaded PDF and thumbnail and preview images of that PDF) that take up 2MB of disk space. So for every extra 500 eprint items you will need an extra 1GB of disk. However, if you intend to upload lots of videos, images, or large documents, then this requirement will be higher. On top of the space needed for uploaded documents and associated files you will need approximately 5GB for installing the operating system. The disk space required by the database is difficult to determine, as this is dependent on a number of different factors but 1MB per eprint item.
=== Example usage requirements ===
* Small repository: 1000 eprint items
** Operating system: 5GB
** Upload and associated files: 2MB x 1000 = 2GB
** Database: 1MB x 1000 = 1GB
** '''TOTAL:''' 8GB (15GB to give room for expansion)
* Medium-sized repository: 10,000 eprint items
** Operating system: 5GB
** Upload and associated files: 2MB x 10,000 = 20GB
** Database: 1MB x 10,000 = 10GB
** '''TOTAL:''' 35GB (50GB to give room for expansion)
* Large repository: 100,000 eprint items
** Operating system: 5GB
** Upload and associated files: 2MB x 100,000 = 200GB
** Database: 1MB x 100,000 = 100GB
** '''TOTAL:''' 305GB (350-400GB to give room for expansion)

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, and to suppress the normal warning about no documents attached look in '''[archive_root]/cfg/cfg.d/eprint_warnings.pl'''.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do
<syntaxhighlight lang="bash">
./configure --help
</syntaxhighlight>
for details.

== How do I get the body HTML of a page without the template around it? ==
This is handy for dynamically linking EPrints content into other sites.

For "view" pages you need to add the option <code>include=>1</code> to the view configuration. This will cause [[API:bin/generate_views|generate_views]] to make a ''.include'' page in addition to the ''.html'' page. The ''.include'' page will have no template around it.

For dynamic pages, i.e. those under ''/cgi/'', you can add the cgi parameter <code>mainonly=yes</code>. E.g. <code><nowiki>http://tryme.demo.eprints-hosting.org/cgi/latest?mainonly=yes</nowiki></code>

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, neither the submission nor creation date, it should still give a good indication.
<syntaxhighlight lang="sql">
select count(*), year(datestamp), month(datestamp)
from archive
group by year(datestamp),month(datestamp)
order by year(datestamp),month(datestamp);
</syntaxhighlight>

== I've edited the template (or other config file) but nothing seems to have changed - why? ==

While EPrints tries to automatically reload when a configuration file is changed you may need to reload the Web server for changes to take effect. See also the [[API:bin/epadmin|epadmin reload]], the [[API:bin/generate_static|generate_static]] and [[API:bin/generate_views|generate_views]] commands.

= How do I add a metadata field to a live repository? =
See [[Adding a Field to a Live Repository]].

= Installation Related Questions =

== When running a script I get the error "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead by <code>su - eprints</code>.

== title and fulltext search returns no results, but date search does ==

The indexer daemon is probably not running or is not working correctly, see [[API:bin/indexer|indexer]].

== I don't want to give epadmin my mysql root password. What is the alternative? ==
<syntaxhighlight lang="sql">
mysql> CREATE DATABASE myrepo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL PRIVILEGES ON myrepo.* TO myrepo@localhost IDENTIFIED BY 'secret';
Query OK, 0 rows affected (0.52 sec)
</syntaxhighlight>

Then provide the database name, user name and password to the '''[[API:bin/epadmin|epadmin]] create''' command.

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

<syntaxhighlight lang="perl">
my $ds = $repo->dataset( "eprint" );
my $eprint = $ds->dataobj( 23 );
my $value = $eprint->value( "editors" );
</syntaxhighlight>

See [[API:EPrints/DataObj|DataObj]].

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<syntaxhighlight lang="perl">
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "error, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</syntaxhighlight>

Main Page

2025-02-25T09:10:20Z

Th.lauke@arcor.de: links updated due to restructuring eprints.org

[[Category:Howto]]__NOTOC__
= Welcome to the EPrints Wiki =

This wiki contains technical and user-contributed documentation for the [[Introduction|EPrints repository software]].

[http://tryme.demo.eprints-hosting.org/ Demoprints] is our live, online server that allows anyone to try EPrints without having to install it first. There are also [http://pub.demo.eprints-hosting.org/ examples] of various 'flavours' of EPrints available to view as well as some more information on the [https://eprints.org/ EPrints project] and related activities.

==New to EPrints?==

Found out more through our:
* [[EPrints Glossary]] - Descriptions of the terminology used within EPrints repository software.
* [[:Category:Training Video|Video Training Course]]
* [[EPrints_Manual|Documentation]]
* [[Working Groups]]
* Mailing lists - There are two mail lists that you might like to join and where you can ask for help and share ideas:
** '''[[eprints-tech Mailing List|The EPrints Technical Mailing List]]'''
*** If you have technical questions, or a part of your EPrints installation is not working properly, this group has people who might be able to help!
*** [[eprints-tech Mailing List|Click here]] for information about [[eprints-tech Mailing List#Subscription_Options|subscribing to this list]] or [[eprints-tech Mailing List#List_Archives|reading its archives]].
** '''[https://groups.google.com/forum/#!forum/eprints-uk-user-group The EPrints User Group Google Group]'''
*** This group is for anyone involved in using EPrints. Ask questions, share ideas, hear about forthcoming meetings.
* How to [[Main_Page#Contributing_to_the_Wiki|contribute to the EPrints wiki]]
* EPrints source code on GitHub:
** Core and major plugins - https://github.com/eprints
** Community code sharing - https://eprintsug.github.io and the repositories at https://github.com/eprintsug

== Download EPrints ==

{{Download}}

==Installation==

* [[:Category:Installation|Installing]] EPrints on various platforms

==[[New_Repository | Getting Started]]==

* [[EPrints Manual|EPrints 3 Documentation]]
* [[Perl 101 for EPrints]]
* [[Frequently Asked Questions]]
* [[:Category:Howto|How to ...]]
* [[:Category:Plugins|Plugins and Bazaar packages for EPrints]]
* [[:Category:Training Video|EPrints Training Course]]

==Getting Support==

* [https://www.eprints.org/eprints-services/ EPrints Services] - premium support, training and hosting from EPrints experts
* [[Contact]] - mailing lists, bug reports etc.
* [[User group meetings]] - regional meetings for users, which often have notes, presentations and information of general interest

==Add-ons, patches and translations==

* As of version 3.3 EPrints can now install plugins and translations through the [https://bazaar.eprints.org EPrints Bazaar] the wiki also has information about [[:Category:EPrints Bazaar|packaging plugins for the Bazaar]].
* The [https://files.eprints.org/ EPrints Files Repository] contains add-on and 3rd party scripts, patches and translations. This also provides an archive of all previous EPrints releases (3.0 onwards).
* [[:Category:Plugins|Plugins]]: Some Wiki pages about scripts and patches.

{{Register}}

==Contributing to EPrints==

* [[Usability|EPrints usability]]
* New features in EPrints - [[:Category:Releases|released]] and [[:Category:Planned Releases|proposed]]
* [[How to contribute|How to contribute to EPrints development]]
* [https://github.com/eprints/eprints3.4 EPrints 3.4 on GitHub] - Codebase, releases and issues tracker for EPrints 3.4.
* [https://github.com/eprints/eprints3 EPrints 3.3 on GitHub] - Codebase, releases and issues tracker for EPrints 3.3 (legacy).

== Content management ==

* [[Digital preservation]]: managing content for longer-term access and use

Import Files

2025-02-24T18:00:33Z

Th.lauke@arcor.de: updated to 3.4

[[Category: Howto]]

Here is a minimalist XML file to import local files into EPrints:

<?xml version='1.0' encoding='utf-8'?>
<eprints>
<eprint>
<documents>
<document>
<files>
<file>
<filename>''/valid/local/path/2/thumb.jpg''</filename>
</file>
</files>
<format>image</format>
<security>public</security>
</document>
</documents>
<eprint_status>archive</eprint_status>
<userid>''numericID''</userid>
<type>image</type>
<creators>
<item>
<name>
<family>''Surname''</family>
<given>''givenName''</given>
</name>
</item>
</creators>
<title>''Importtest''</title>
</eprint>
</eprints>

Note that this also set the <code>title</code> and the <code>creators</code>. You can override the saved <code>userid</code> by <code>--user ''modID''</code> when importing with the <code>~/eprints/bin/import</code> script (run it with <code>--help</code> to see all options, <code>--parse-only</code> e.g.).

This will put the eprint object straight into the live repository by <code><eprint_status>archive</eprint_status></code>! You may wish to place it into the user area by <code><eprint_status>inbox</eprint_status></code> or into the editorial review by <code><eprint_status>buffer</eprint_status></code> instead.

For a proper overview of any input field, enter all relevant data into the form and export your entry by
~/eprints/bin/export ''repoID'' eprint XML ''entryID''.

See also [[Import From URL]] and XML standardisation page [[EPData XML Representation]].

EPrints 3.4.6

2025-02-19T15:10:15Z

Th.lauke@arcor.de: typo removed, formatting added

{{releasenotes}}

This page contains information about the provisional EPrints v3.4.6 tag and release on GitHub.

== Release Notes ==
EPrints 3.4.6 is now available on [https://github.com/eprints/eprints3.4/releases/tag/v3.4.6 GitHub].
* '''Zero codename:''' Creme Brulee Cryoseism
* '''Publications flavour codename:''' Affogato Snowmelt

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

=== Changes Since 3.4.5 ===

==== New Functionality ====
* Adds <code>unlink_lib</code> option to <code>tools/epm</code>.
* Adds <code>--to-link</code> flag to <code>unpack</code> option of <code>tools/epm</code> to allow an EPM file to be unpack so it can subsequently be deployed by <code>link_lib</code> option.
* [https://github.com/eprints/eprints3.4/issues/340 Provide support for converting HEIC and WEBP thumbnails]
* Adds support for setting default reply-to when separate <code>$c->{adminemail}</code> and <code>$c->{sendermail}</code>
* [https://github.com/eprints/eprints3.4/issues/388 Allows certain URL paths to be blocked for certain IPs]
* [https://github.com/eprints/eprints3.4/pull/387 Initial Signposting integration]

==== Security and Privacy Improvements ====
* [https://github.com/eprints/eprints3.4/issues/347 Implement stronger password hashing]
* [https://github.com/eprints/eprints3.4/issues/344 Creates and enables <code>export_privacy</code> setting to prevent export formats that include email addresses to be publicly accessible by default].
* Ensure <code>ga.js</code> is always served on HTTPS
* Makes sure <code>cache</code> parameter value provided by search form is a number to prevent URL injection.

==== General Improvements ====
* [https://github.com/eprints/eprints3.4/issues/336 Implement Recaptcha field to work with Google ReCAPTCHA v3]
* [https://github.com/eprints/eprints3.4/issues/339 Sets <code>ignore_login_ip = 1</code> by default if HTTPS is enabled.
* [https://github.com/eprints/eprints3.4/issues/345 Improvements Accessibility based on issues raised by axe DevTools]
* [https://github.com/eprints/eprints3.4/issues/348 Improves message when file retrieval fails]
* Adds <code>.gitignore</code> for ingredients other than those included, so those deploying EPrints using Git do not see new ingredients as uncommitted.
* Updates and tidies <code>SystemSettings.pm</code> and <code>SystemSettings.pm.in</code>
* [https://github.com/eprints/eprints3.4/issues/355 Adds function to get local path on disk for file object]
* [https://github.com/eprints/eprints3.4/pull/357 Overwrites media video stream if incoming stream is higher res]
* Uses <code>export</code> version of citation if exists (rather than <code>default</code>) for HTML export of data objects
* [https://github.com/eprints/eprints3.4/pull/359 Adds title attribute for preview images to display on hover]
* Adds function to test if citation style file exists
* Allows truncated URL linls to set a <code>target</code> attribute
* Provide large icons to be printed by EPC <code>icon</code> function
* Added EPC <code>text</code> function to print out phrases into HTML attributes values
* [https://github.com/eprints/eprints3.4/issues/362 Allows certain HTML formatting tags in imports, (e.g. from PubMed)]
* Adds title for action button image
* Allows fields of various types to be more customisable in search forms
* Reports useful error message if user tries to remove subject that has children
* [https://github.com/eprints/eprints3.4/issues/353 Allows way to pass timeout to indexer daemon]
* [https://github.com/eprints/eprints3.4/pull/351 Aligns headings when Itemref occurs within Compound Metafield]
* Log failure if email attempts send with <code>to_email</code> or <code>to_list</code> set
* Allows <code>EPrints::Repository::render_option_list</code> to render select box as disabled
* Ensures more consistent use of space for results listings where div rather than table rows are now used for better Accessibility
* Better margin for search results toolbar (e.g. Batch Edit)
* [https://github.com/eprints/eprints3.4/issues/367 Organise fields under stage in EPrint::View screen by workflow rather than data object]
* [https://github.com/eprints/eprints3.4/issues/370 Rewrite CitationCache code to use EPrints API rather than SQL query]
* [https://github.com/eprints/eprints3.4/issues/360 Allow "make open access" on request copy responses a disable-able field]
* [https://github.com/eprints/eprints3.4/issues/376 Allow signed in user to be logged in Apache access logs]
* [https://github.com/eprints/eprints3.4/pull/382 Adds lastmod attributes to entries in sitemap]
* [https://github.com/eprints/eprints3.4/issues/381 Add <code>threads</code> option to ffmpeg invocations]
* [https://github.com/eprints/eprints3.4/issues/392 Stop unnecessarily generating list of user's eprints twice for Manage Deposits page load]
* [https://github.com/eprints/eprints3.4/issues/374 Uses <code>Text::Unidecode</code> primarily to tokenize input for indexing] (rather than manually defining mappings)
* [https://github.com/eprints/eprints3.4/issues/373 Rework cpan_modules.pl to install all required Perl modules]
* Allows EPC to render icon without a link
* Adds commented out config option <code>show_ids_in_log</code>
* Removes long since deprecated pagehooks functionality
* Removes irrelevant <code>dbsid</code> config setting
* Improvements to simplify login monitoring configuration
* Remove reference to defunct <code>quiet</code> config setting

==== Bug Fixes ====
* Fixes [https://github.com/eprints/eprints3.4/issues/332 Downloading document from preview image does not work for some filenames]
* Fixes [https://github.com/eprints/eprints3.4/issues/333 Do not add <code>requester_userid</code> by default as access table can take a long time to add new fields. However, ensure if field exists it is set to current user ID, if set].
* Fixes serialization of EPM for <code>build</code> option of <code>tools/epm</code>.
* Fixes issues with <code>disable</code> and <code>unpack</code> options for <code>tools/epm</code>.
* [https://github.com/eprints/eprints3.4/issues/342 Duplicated "_label" span id]
* Fixes [https://github.com/eprints/eprints3.4/issues/341 Tab children deemed decorative]
* Fixes bug preventing user password updates from command line.
* Fixes intermittent issue with <code>xmlns:xsi</code> attribute being defined twice on some <code>/cgi/oai2/...</code> pages.
* Check that <code>uri</code> of relation is set before comparing its value for <code>EPrints::DataObj::remove_dataobj_relations</code>
* Check that <code>uri</code> of relation is set before comparing its value for <code>EPrints::MetaField::Relation::to_sax_basic</code>
* Check URL is set before testing its length in <code>EPrints::Extras::render_url_truncate_end</code>
* Fixes <code>EPrints::XML::SAX::Writer::escape</code> to make sure <code>$str</code> is set before applying regular expression
* Export bar form should use <code>rel_cgipath</code> not <code>http_cgiroot</code>
* Actually use <code>size</code> when calling <code>EPrints::DataObj::Document::render_icon_link</code>
* Ensure lookup of keyname is set before using it in <code>EPrints::Database::get_dataobjs</code>
* Testing an import should set the <code>filename</code> parameter like it would in a real import
* Checks <code>$c->{oai}->{comments}</code> is set before iterating over it.
* Prevents bin script from complaining about email-less users.
* Fixed EPC <code>contains</code> function to return a boolean value rather than a TRUE/FALSE string.
* [https://github.com/eprints/eprints3.4/pull/365 Allows documents to <code>redo_thumbnails</code> even if they have no parent eprint]
* Fixes wrong optione name for loading external DTDs in XML
* [https://github.com/eprints/eprints3.4/issues/366 Fixes overloading of etaField <code>render_quiet</code> attribute by introducing <code>render_column_quiet</code> attribute
* [https://github.com/eprints/eprints3.4/issues/369 Fixes unsecure request when uploading file]
* [https://github.com/eprints/eprints3.4/issues/371 Fix encoding issues for bespoke Export plugins]
* [https://github.com/eprints/eprints3.4/issues/334 Using page_id pin in page templates breaks editing static pages in web interface]
* Checks value is set before performing a regular expression replace in <code>EPrints::MetaField::Search::form_value_basi</code>
* [https://github.com/eprints/eprints3.4/issues/375 Return more appropriate <code>500</code> rather than <code>404</code> HTTP code if document present but database query fails]
* [https://github.com/eprints/eprints3.4/issues/377 Fixes drag 'n' drop issues leading to zero byte files]
* [https://github.com/eprints/eprints3.4/issues/378 Fixes "More input rows" button affecting layout of Compound field tables in workflow]
* Ensures clicking tabs on abstract pages does not reload page
* [https://github.com/eprints/eprints3.4/pull/380 Ensures fields sent in autocompleter requests are encoded]
* [https://github.com/eprints/eprints3.4/issues/383 Allows phrase editor to add phrases for alternative languages]
* [https://github.com/eprints/eprints3.4/issues/385 Fixes bug with edit subjects if ID field value is too long]
* Fixes warnings produced when <code>readonly</code> or <code>show_help</code> MetaField attributes are not defined when expected
* [https://github.com/eprints/eprints3.4/issues/48 Fixes further issue with <code>toform</code> attribute for <code>itemref</code> MetaField]
* Fixes warnings when using <codeEPrints::UTils::compare_version function
* [https://github.com/eprints/eprints3.4/issues/323 Fixes ancestor numbers (of items) in subject-based browse views]
* [https://github.com/eprints/eprints3.4/issues/390 Fixes slow page loads when user has lots of items under Manage Deposits]
* [https://github.com/eprints/eprints3.4/issues/249 Reverts changes to implement subject MetaField's <code>top</code> attribute as a function] (Best done through conditional in the workflow)
* Fixes XSLT import/export plugins so they no longer prevent EPrints being run using Apache MPM Event (i.e. threaded)
* [https://github.com/eprints/eprints3.4/issues/384 Ensure search pages respect <code>template</code> specified in their configuration]
* Makes sure XML converted to string does not contain any control/non characters that might break if they attempt to be rendered within XML.
* Fixes wrong config variable loads for <code>citation_default</code> for Dublin Core and simple export.
* Extends sanitization invalid characters for values of ID metadata fields and their subclasses.
* Fixes various typos
* [https://github.com/eprints/eprints3.4/issues/395 Fixes broken <code>eprint_status</code> filters when <code>get_users_owned_eprints</code> configuration function is defined]
* [https://github.com/eprints/eprints3.4/issues/394 Fixes incorrect white space in citations rendered in emails]

== Known Issues ==
=== Running generate_apacheconf with an archive without a cfg/static/javascript/auto/ directory ===
If you are upgrading an EPrints repository and your archive(s) do not have a <code>cfg/static/javascript/auto/</code> directory then <code>bin/generate_apacheconf</code> will fail. This is because 3.4.6 [https://github.com/eprints/eprints3.4/issues/369 introduces] code that makes sure that the maximum upload limit is configured to be the same in the Apache configuration and in EPrints' JavaScript, which prevents you from trying to upload files larger than a certain size. This is useful because if you just updated the JavaScript, EPrints would allow the upload to start but would then fail when the Apache limit was reached. So not only would you not be able to upload the file but you would waste a load of time and possibly not understand why the upload failed.

To fix this issue for this version of EPrints, just make sure your archive (or archives) all have a <code>cfg/static/javascript/auto/</code> before running <code>bin/generate_apacheconf</code>. Future versions of EPrints will automatically create this directory if it does not already exist.

=== Subject search does not work in workflows ===
If you have a subject field which renders as a subject tree in a workflow, the search form will not work. This is due to the [https://github.com/eprints/eprints3.4/issues/246 fix for ensuring Xapian respect a MetaField's <tt>text_index</tt> value]. This has the consequence of not indexing the <tt>ancestors</tt> field for subjects. This is used by the search to filter out subjects that are not part of the subject sub-tree for a particular MetaField. [https://github.com/eprints/eprints3.4/commit/3fbd47ccc0d9e66514455c693b62b902790e3326 This patch] fixes [https://github.com/eprints/eprints3.4/issues/411 the issue]. However, you will also need to re-index all subjects:
EPRINTS_PATH/bin/epadmin reindex ARCHIVE_ID subject

=== Approved document requests still force user to login ===
This issue was caused by setting the <code>samesite</code> attribute for the <code>eprints_doc_request</code> cookie to <code>Strict</code>, this cookie is intended to allow the user to access the restricted document for the remainder of their session. Changing this attributes means some browsers (e.g. Firefox) still send the user to a login page even when clicking the approved request link in the email they received. This is because the change made to the cookie prevents its from being stored because <code>/cgi/process_request</code> never fully serves a page. [https://github.com/eprints/eprints3.4/commit/278b5e599dc9f6aa1e4a20f3b211afabb2a4ea9a This patch] fixes the [https://github.com/eprints/eprints3.4/issues/413 the issue].

== Further Planned Features and Improvements ==
See [https://github.com/eprints/eprints3.4/milestone/8 3.4.7 milestone on GitHub] for more details.

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

Upgrading

2024-11-01T13:19:18Z

Th.lauke@arcor.de: URL/version upgrade

{{manual}}

== Upgrade between same series versions of EPrints ==
If you are upgrading between the same series versions of EPrints (e.g. 3.3.15 to 3.3.16 or 3.4.2 to 3.4.3) then the upgrade process is somewhat more straightforward that upgrading between EPrints series versions (e.g. 3.3.16 to 3.4.3). This page was originally written for upgrading between 3.3 series versions, '''[[Upgrading between EPrints 3.4 versions]]''' provides additional specific information about EPrints 3.4 series.

=== From a Linux Package Manager ===
If you have installed from the Deb or RPM package, then you can just upgrade this. However, it is recommended that you have done a backup before doing this. Also if this is on a production server, that you do this during an extended period of scheduled downtime and have previously tested the upgrade on a pre-production server.

Once the package upgrade has completed make sure to run both ''epadmin upgrade'' and ''epadmin update'' on all archives. The package manager may only tell you need to run ''epadmin upgrade'' but ''epadmin update'' is also needed to ensure newly added fields to data objects are also incorporated.
/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID

=== From GitHub ===
If you have installed with GitHub, the preferred method for production repositories, you can update to the latest version using the following commands, substituting ''y'' for the version you want and ''x'' for the 3 or 4 depending on whether you are upgrading between EPrints 3.3 or 3.4 series:

git fetch origin
git merge tags/v3.x.y

This should warn you if you have made any locally uncommitted changes. You may need to use ''git stash'' to move these temporarily and reintegrate after updating from GitHub.

Once updated to the intended tagged release version any resolved and local uncommitted changes then make sure to run both ''epadmin upgrade'' and ''epadmin update'' on all archives and then reload the webserver and EPrints indexer, e.g.
/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID
apachectl graceful
/opt/eprints3/bin indexer restart

=== From a Tarball ===
Although not impossible it is strongly discouraged to upgrade from a tarball. One major reason not to do this is that if you have made any local changes other than to your original archive's configuration, it will be difficult to ensure all these modifications are retained. However, if you wish to do this, you can follow the instructions below, (as the eprints user unless otherwise stated):

==== Downloading and Unpacking 3.3 ====
<ol>
<li> Download the tarball from files.eprints.org, (e.g. https://files.eprints.org/2306/5/eprints-3.3.16.tar.gz)</li>

<li> As the root user, unpack the tarball under the same parent path as your existing EPrints and change the ownership of this whole directory structure</li>

cd /opt
tar -xzvf eprints-3.3.16.tar.gz
mv eprints-3.3.16 eprints3_new
chown -R eprints:eprints /opt/eprints3_new

</ol>
==== Downloading and Unpacking 3.4 ====
<ol>
<li> Download the main tarball from files.eprints.org, (e.g. https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz)</li>
<li> Download the publications tarball from files.eprints.org, (e.g. https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz)</li>
<li> As the root user, unpack the tarball under the same parent path as your existing EPrints and change the ownership of this whole directory structure</li>

cd /opt
tar -xzvf /home/eprints/eprints-3.4.6.tar.gz
tar -xzvf /home/eprints/eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6 eprints3_new
chown -R eprints:eprints /opt/eprints3_new

</ol>

==== Installing and Configuring ====

<ol>
<li> As the root user, stop Apache and EPrints' indexer.</li>

apachectl graceful-stop
/opt/eprints3/bin/epindexer stop

<li> Move the archive(s) from your old EPrints to your new one, e.g.</li>

mv /opt/eprints3/archives/* /opt/eprints3_new/archives/

<li> Copy SystemSettings.pm to your new EPrints as well as site-wide settings</li>

cp -p /opt/eprints3/perl_lib/EPrints/SystemSettings.pm /opt/eprints3_new/perl_lib/EPrints/
cp -pR /opt/eprints3/cfg /opt/eprints3_new/cfg
cp -pR /opt/eprints3/site_lib /opt/eprints3_new/site_lib

<li> If you are aware of any local modifications to files under your EPrints path (e.g. /opt/eprints3) but outside the archives directory then compare these files using diff to work out how your local changes can be integrated. E.g.</li>

diff /opt/eprints3/perl_lib/EPrints/MetaField/Date.pm /opt/eprints3_new/perl_lib/EPrints/MetaField/Date.pm

<li> As the root user, switch round the old and new versions of EPrints, e.g.</li>

mv /opt/eprints3 /opt/eprints3_old
mv /opt/eprints3_new /opt/eprints3

<li> Run epadmin test to check there are no configuration issues, e.g.</li>

/opt/eprints3/bin/epadmin test

<li> Run ''epadmin upgrade'' and ''epadmin update'' to deploy any structural changes or addition of fields to the database, e.g.</li>

/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID

<li> Restart EPrints' indexer.</li>

/opt/eprints3/bin/epindexer start

<li> As the root user, restart Apache.</li>

apachectl restart

<li>Don't forget to reinstall your Bazaar packages.</li>
</ol>

== Upgrading to EPrints to 3.3 ==
Upgrading from older 3.1 and 3.2 versions of EPrints to 3.3 is somewhat more involved. Please see the following guides:
* [[Upgrading from 3.1]]
* [[Upgrading from 3.2]]

== Upgrading to EPrints 3.4 ==
To upgrade to EPrints 3.4 you will need to already be running a version of EPrints 3.3. Ideally at least 3.3.12, which has the following guide:
* [[Upgrading 3.3.12+ to 3.4]]

Upgrading 3.3.12+ to 3.4

2024-11-01T13:14:54Z

Th.lauke@arcor.de: URL/version upgrade

These instructions help you upgrade EPrints 3.3.16+ (or any newer version of EPrints 3.3) to EPrints 3.4 while keeping all your eprints, documents and local configuration changes.

It assumes your EPrints 3.3.16+ was installed using a tarball (tar.gz) file and installed in <code>/opt/eprints3</code>. The commands in these instructions assume Centos 7 OS and run as the eprints user, unless it is stated to run as the root user.

=Upgrade from Tarball=

==Pre-upgrade==
* If you have local modifications to the core files (in /opt/eprints3/perl_lib), you may need to manually migrate your changes.
* If you use Twitter integration, use CPAN to install LWP::Authen::OAuth as this is no longer in perl_lib. To do so, as root run:
cpan LWP::Authen::OAuth
* Download each of the Bazaar plugins you have installed as EPM files from your existing repository.
* Make a backup of your local configurations.

==Process==
We will move your existing eprints 3.3.16+ installation from <code>/opt/eprints3/</code> to <code>/opt/eprints3.3</code>, install eprints 3.4, then migrate your configurations into EPrints 3.4; cf. [https://wiki.eprints.org/w/Category:Installation Category Installation]
<br>
'''as root'''
apachectl stop
cd /opt
eprints3/bin/epindexer stop
mv eprints3 eprints3.3

* Download EPrints 3.4 core and publication flavour tarball and install them from [http://files.eprints.org/ Files.eprints.org] with
wget https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz
wget https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz
'''as root'''
cd /root
tar xvzf eprints-3.4.6.tar.gz
tar xvzf eprints-3.4.6-flavours.tar.gz

* Have a look to <code>/root/eprints-3.4.6/INSTALL</code> for some local adaption options.
'''as root'''
cd eprints-3.4.6
./configure
make install

* Move your current repository from 3.3 to 3.4
'''as root'''
cd /opt
mv eprints3.3/archives/ARCHIVENAME eprints3/archives/
* After moving, make sure all files inside <code>/opt/eprints3</code> are still owned by eprints user and belongs to eprints group, thus
'''as root'''
chown -R eprints:eprints /opt/eprints3

* Create <code>/opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl</code> to set the appropriate flavour, typically 'pub', i.e.
echo "\$c->{flavour} = 'pub';" > /opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl

* create a symbolic link to <tt>default.xml</tt>
cd /opt/eprints3/archives/ARCHIVENAME/cfg/templates/ (or /opt/eprints3/archives/ARCHIVENAME/cfg/lang/en/templates/
ln -s default.xml default_internal.xml

* Audit each of their local config files against the pub_lib flavours config files:
#The first <code>diff</code> below will identify all the files that are the same. If so, delete the ones in <code>archives/ARCHIVENAME/cfg/cfg.d/</code>. You almost certainly should not find any, as the files in <code>flavours/pub_lib/cfg.d</code> will at very least have updated copyright/licensing boilerplate.
#The second <code>diff</code> will find where files exists in both directory are different. Here they should be compared to see, if the local differences are superficial (e.g. slightly different comments or spacing) and therefore can be removed. Also the pub_lib flavour version may fix an outstanding bug or perform the required functionality more succinctly. If this is the only change, then the local archive version can be deleted, otherwise the change should be incorporated in the local version.
cd /opt/eprints3/
diff -rs archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ are identical$'
diff -rq archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ differ$'

<ul><li>Compare <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> with <code>flavours/pub_lib/cfg/cfg.d/eprint_fields_pub.pl</code> maybe with the help of [http://diffuse.sourceforge.net/download_de.html ''diffuse''] to overcome this business easier:<ul>
<li>If these are different and fields are present in <code>eprint_fields_pub.pl</code> and not <code>eprint_fields.pl</code> or the definitions (e.g. type, options, etc.) for the same field are different then:<ol>
<li>Copy <code>flavours/pub_lib/cfg.d/eprint_fields_pub.pl</code> to their archive's <code>cfg/cfg.d/</code>.
<li>Modify the fields in their archive's <code>cfg/cfg.d/eprint_fields_pub.pl</code> where they have different definitions (e.g. type, options, etc.) to those in <code>eprint_fields.pl</code>.
<li>Remove all fields in their archive's <code>cfg/cfg.d/eprint_fields.pl</code> where they also occur in their archive's <code>cfg/cfg.d/eprint_fields_pub.pl</code>, no matter if already transferred due to previous item or initially the same.</ol>
<li>If there are only additional fields in <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> then just do the last step.
<li>If the two files are identical then you need to do nothing. However, this is extremly unlikely.
</ul>
Finally, the specification is still the same, but mostly split into two distinct files, which obey the known rule ''Local version overrides central one''.</ul>
* Synchronise <code>archives/ARCHIVENAME/cfg/cfg.d/epm.pl</code> with <code>ingredients/bazaar/cfg.d/epm.pl</code>, i.e. remove <code>archives/ARCHIVENAME/cfg/cfg.d/epm.pl</code> in case of ''no'' local modifications.

* Ensure the following bazaar files are disabled by renaming to FILENAME.pl''.disabled''. Once they have been reinstalled via the Bazaar then they can be moved back into place. Using <code>epadmin test</code> is a good way of discovering which files need this doing, but below is a list of common files that should be temporarily moved, if they exist in your archive's <code>cfg/cfg.d/</code> directory:
mv z_orcid_support.pl z_orcid_support.pl.disabled
mv zz_hefce_oa_fields.pl zz_hefce_oa_fields.pl.disabled
mv zz_rioxx2.pl zz_rioxx2.pl.disabled
mv z_meprints.pl z_meprints.pl.disabled

* As the eprints user, run <code>epadmin update</code> to add any new fields that were not previously present (typically this is embargo_reason for documents and requester_email for request)
/opt/eprints3/bin/epadmin update ARCHIVENAME

* Generate new Apache configuration and as root test (fixing any issues) and restart Apache after necessary site-specific adaption are done.
/opt/eprints3/bin/generate_apacheconf --system --replace ARCHIVENAME
'''as root'''
apachectl configtest
apachectl restart

* Once confirming that EPrints is generally working. Go to Admin->Bazaar then install the Bazaar plugins you downloaded from your 3.3 repository before starting the upgrade process. This can be done by going to the Available tab in the Bazaar and strolling to the Upload section at the bottom. Unfortunately, you cannot do a bulk upload, so will need to install each plugin in turn.

* Move back the files you renamed to FILENAME''.disabled'' earlier, the epindexer into service and reload Apache
'''as root'''
/opt/eprints3/bin/epindexer start
apachectl graceful

* Finally, run <code>generate_static</code> to make sure all pages are regenerated with any changes to configuration.
/opt/eprints3/bin/generate_static ARCHIVEID

==Notes==
* 3.4 does not automatically update an archive's <code>html/en/</code> files. If there are any bugs with broken JavaScript or unexpected CSS, try deleting the archives <code>html/en/javascript/auto.js</code> or <code>html/en/style/auto.css</code>. Similarly if a static page cannot be changed try deleting it under the archive's <code>html/en/</code> or running <code>generate_static</code>.
* If some Perl modules are giving out error messages like:
Can't locate object method "new" via package "EPrints::Plugin::Event::PIRUS" at /opt/eprints3/bin/../perl_lib/EPrints/PluginFactory.pm line 276.
Can't locate object method "new" via package "EPrints::Plugin::Screen::EPrint::Box::Tools::SUPER" at /opt/eprints3/site_lib/plugins/EPrints/Plugin/Screen/EPrint/Box/Tools.pm line 12.
It is because their parent module has not been initialised. This happens when the parent module lives in perl_lib, and the problem module live in elsewhere; e.g. parent module of PIRUS(Event.pm) is in <code>./perl_lib</code>, while the <code>PIRUS.pm</code> is in <code>./pub_lib</code>.
Just need to <code>use</code> the parent module before the <code>ISA</code> line:
use EPrints::Plugin::Event;

[[Category:Upgrading]]

Installing EPrints on Debian/Ubuntu

2024-10-30T18:17:55Z

Th.lauke@arcor.de: version update

[[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-base-bin 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]]

Installing EPrints on Debian/Ubuntu

2024-10-30T18:17:14Z

Th.lauke@arcor.de: URL & version update

[[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-base-bin 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.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
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

2024-10-30T18:14:20Z

Th.lauke@arcor.de: URL & version update

[[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-base-bin 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.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
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/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 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]]

Upgrading

2024-05-08T15:50:07Z

Th.lauke@arcor.de: typos removed, versions updated

{{manual}}

== Upgrade between same series versions of EPrints ==
If you are upgrading between the same series versions of EPrints (e.g. 3.3.15 to 3.3.16 or 3.4.2 to 3.4.3) then the upgrade process is somewhat more straightforward that upgrading between EPrints series versions (e.g. 3.3.16 to 3.4.3). This page was originally written for upgrading between 3.3 series versions, '''[[Upgrading between EPrints 3.4 versions]]''' provides additional specific information about EPrints 3.4 series.

=== From a Linux Package Manager ===
If you have installed from the Deb or RPM package, then you can just upgrade this. However, it is recommended that you have done a backup before doing this. Also if this is on a production server, that you do this during an extended period of scheduled downtime and have previously tested the upgrade on a pre-production server.

Once the package upgrade has completed make sure to run both ''epadmin upgrade'' and ''epadmin update'' on all archives. The package manager may only tell you need to run ''epadmin upgrade'' but ''epadmin update'' is also needed to ensure newly added fields to data objects are also incorporated.
/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID

=== From GitHub ===
If you have installed with GitHub, the preferred method for production repositories, you can update to the latest version using the following commands, substituting ''y'' for the version you want and ''x'' for the 3 or 4 depending on whether you are upgrading between EPrints 3.3 or 3.4 series:

git fetch origin
git merge tags/v3.x.y

This should warn you if you have made any locally uncommitted changes. You may need to use ''git stash'' to move these temporarily and reintegrate after updating from GitHub.

Once updated to the intended tagged release version any resolved and local uncommitted changes then make sure to run both ''epadmin upgrade'' and ''epadmin update'' on all archives and then reload the webserver and EPrints indexer, e.g.
/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID
apachectl graceful
/opt/eprints3/bin indexer restart

=== From a Tarball ===
Although not impossible it is strongly discouraged to upgrade from a tarball. One major reason not to do this is that if you have made any local changes other than to your original archive's configuration, it will be difficult to ensure all these modifications are retained. However, if you wish to do this, you can follow the instructions below, (as the eprints user unless otherwise stated):

==== Downloading and Unpacking 3.3 ====
<ol>
<li> Download the tarball from files.eprints.org, (e.g. https://files.eprints.org/2306/5/eprints-3.3.16.tar.gz)</li>

<li> As the root user, unpack the tarball under the same parent path as your existing EPrints and change the ownership of this whole directory structure</li>

cd /opt
tar -xzvf eprints-3.3.16.tar.gz
mv eprints-3.3.16 eprints3_new
chown -R eprints:eprints /opt/eprints3_new

</ol>
==== Downloading and Unpacking 3.4 ====
<ol>
<li> Download the main tarball from files.eprints.org, (e.g. https://files.eprints.org/2789/1/eprints-3.4.5.tar.gz)</li>
<li> Download the publications tarball from files.eprints.org, (e.g. https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz)</li>
<li> As the root user, unpack the tarball under the same parent path as your existing EPrints and change the ownership of this whole directory structure</li>

cd /opt
tar -xzvf /home/eprints/eprints-3.4.5.tar.gz
tar -xzvf /home/eprints/eprints-3.4.5-flavours.tar.gz
mv eprints-3.4.5 eprints3_new
chown -R eprints:eprints /opt/eprints3_new

</ol>
==== Installing and Configuring ====

<ol>
<li> As the root user, stop Apache and EPrints' indexer.</li>

apachectl graceful-stop
/opt/eprints3/bin/epindexer stop

<li> Move the archive(s) from your old EPrints to your new one, e.g.</li>

mv /opt/eprints3/archives/* /opt/eprints3_new/archives/

<li> Copy SystemSettings.pm to your new EPrints as well as site-wide settings</li>

cp -p /opt/eprints3/perl_lib/EPrints/SystemSettings.pm /opt/eprints3_new/perl_lib/EPrints/
cp -pR /opt/eprints3/cfg /opt/eprints3_new/cfg
cp -pR /opt/eprints3/site_lib /opt/eprints3_new/site_lib

<li> If you are aware of any local modifications to files under your EPrints path (e.g. /opt/eprints3) but outside the archives directory then compare these files using diff to work out how your local changes can be integrated. E.g.</li>

diff /opt/eprints3/perl_lib/EPrints/MetaField/Date.pm /opt/eprints3_new/perl_lib/EPrints/MetaField/Date.pm

<li> As the root user, switch round the old and new versions of EPrints, e.g.</li>

mv /opt/eprints3 /opt/eprints3_old
mv /opt/eprints3_new /opt/eprints3

<li> Run epadmin test to check there are no configuration issues, e.g.</li>

/opt/eprints3/bin/epadmin test

<li> Run ''epadmin upgrade'' and ''epadmin update'' to deploy any structural changes or addition of fields to the database, e.g.</li>

/opt/eprints3/bin/epadmin upgrade ARCHIVEID
/opt/eprints3/bin/epadmin update ARCHIVEID

<li> Restart EPrints' indexer.</li>

/opt/eprints3/bin/epindexer start

<li> As the root user, restart Apache.</li>

apachectl restart

<li>Don't forget to reinstall your Bazaar packages.</li>
</ol>

== Upgrading to EPrints to 3.3 ==
Upgrading from older 3.1 and 3.2 versions of EPrints to 3.3 is somewhat more involved. Please see the following guides:
* [[Upgrading from 3.1]]
* [[Upgrading from 3.2]]

== Upgrading to EPrints 3.4 ==
To upgrade to EPrints 3.4 you will need to already be running a version of EPrints 3.3. Ideally at least 3.3.12, which has the following guide:
* [[Upgrading 3.3.12+ to 3.4]]

Safe Upgrading

2024-05-08T15:27:23Z

Th.lauke@arcor.de: excluding reproducible dir added, some reformatting

You should really aim to upgrade your EPrints repository about once a year to keep on top of the new developments. Upgrading your EPrints repository can be a very daunting task. The aim of this page is to get people who are not confident about undertaking it into a position where it is safe to do so. Note upgrading is different to migrating (although some of the procedures maybe the same).

==Am I Upgrading?==

Upgrading is when you intend to update eprints code base on a server to a later version. Upgrading covers moves from EPrints 3.x.y to 3.a.b if you want to move from EPrints 2.x.y to 3.a.b then you are undertaking a migration. Also if you are moving your EPrints repository from one server to another you are migrating. Upgrading is just a different sub-version (but same main version) of EPrints on the same server.

==Preparation==

If you are upgrading then there are a number of precautions you can take to ensure the process runs as smoothly as possible. It is impossible to give 100% cast iron guarantee an upgrade will succeed particularly if you have a heavily customised repository so you must make sure that you are in position to roll back in the unlikely event that the upgrade does not go to plan.

It is worth saying at this point that if possible you can ease your fears by performing this task on a development server as a practice run. This technique if available to you is strongly advised.

To prepare you should:

===Tell an adult===

Talk to your system administrator about getting a full system backup made. It is advisable to do this fairly regularly anyway in case of hardware failure or fire (see [[Backups|backing up]]).

You should also speak to who ever you need to get permission from to cause server down time. This is not always required as many upgrades can be done with very little down time but it is best to ask for permission and not use it than find you have to apologize for an unexpected service outage.

===Create a backups directory===

mkdir <eprints_root>/backups

To create a directory to put backups into.

===Check you have enough disk space===

df -h

Will give you a table:
<pre>
Filesystem Size Used Avail Use% Mounted on
/dev/sda5 32G 1.4G 31G 5% /
/dev/sda7 32G 22G 11G 67% /opt
/dev/sda8 41G 24G 18G 59% /usr
/dev/sda6 16G 6.2G 9.9G 39% /var
/dev/sdb1 135G 24G 105G 19% /backup
</pre>

You should make sure that the disk which contains your eprints directory (usually /opt or /usr) is over 50% free. The backup of the archive will take up a similar amount of space to the archive itself so you should check you have enough space for it before starting.

===Backup your database===

cd <eprints_root>/backups

to change to your backups directory

mysqldump -u <db_user> -p <db_name> > <archive_id>.archive.backup-<year>-<month>-<day>.sql

at the prompt you will need to enter the ''password''. If your repository is large this step can take a while. The purpose of the elaborate file name is so that at a glance you can tell what this file is. Also if you have multiple backups then ordering them alphabetically will put the backups for that archive in date order so you can find your most recent backup. Ending the file with .sql means you know it is a database backup.

If you do not know your <code>db_user</code>, <code>db_name</code> or ''password'' for the above step you can find it by typing:

cat <eprints_root>/archives/<archive_id>/cfg/cfg.d/database.pl

You should now have a .sql file containing your database backup in your <eprints_root>/backups directory.

===Backup your archive===

cd <eprints_root>/archives/

and then

tar czf <eprints_root>/backups/<archive_id>.archive.backup-<year>-<month>-<day>.tgz <archive_id>

to create a zipped backup of your entire repository including static pages, documents, files and configuration. This can take a long time, for large repositories it can be several hours.

Depending on the output of
du -sh {var/xapian,html}
you may prefer if you are short of disk space to exclude some big directories which are reproducible (maybe in some hours!). If it makes sense for you backup
your archive by
tar --exclude=<archive_id>/{var/xapian,html} -cvzf <eprints_root>/backups/<archive_id>.archive.backup-<year>-<month>-<day>.tgz <archive_id>

===Backup your perl_lib===

This step should not be necessary if you have followed the guide for [[Tips_to_write_plugins|making safe plugins]]. If you didn't follow the guide and modified <code>perl_lib</code> (for shame) or you are particularly paranoid you may want to backup your <code>perl_lib</code> directory.

cd <eprints_root>

and then

tar czf backups/<archive_id>.archive.backup-<year>-<month>-<day>.tgz <perl_lib>

You should now be ready to upgrade.

==Upgrading==

Make sure you have re-read the list of things to know about upgrading your specific EPrints version up to the one you are moving to.

[[Category:Out of Date]]
[[Category: Upgrading]]

EPrints 3.4.5

2024-05-08T14:04:05Z

Th.lauke@arcor.de: link added

{{releasenotes}}

== Release Notes ==
EPrints 3.4.5 is now available on [https://github.com/eprints/eprints3.4/releases/tag/v3.4.5 GitHub] and [https://files.eprints.org/2789/ 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].

== Planned Development ==
See [[EPrints 3.4.6]]

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

How to Fix UTF-8 problems

2024-02-19T14:18:07Z

Th.lauke@arcor.de: Categories modified

This is a guide to bug fixing UTF-8 problems you might find around EPrints. It should be particularly helpful for people creating plugins, for example custom InputForm::Components.

[[Category:Obsolete‏‎]]
[[Category:Documentation Needed‏‎]]

Common MySQL Problems with EPrints

2024-02-19T13:51:51Z

Th.lauke@arcor.de: link/category added

[[Category:Work_in_Progress]]
[[Category:Documentation Needed‏‎]]
{{Beware | If you plan to follow any of the resolutions described below, make sure you have backed up the database, so you can restore it if things go wrong.}}

There are a number of common problems that EPrints can have with MySQL, which often result from the increasing size and complexity of an EPrints repository.

== Row size too large ==
=== Example error message ===
DBD::mysql::st execute failed: Row size too large (> 8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help. In current row format, BLOB prefix of 768 bytes is stored inline. at /opt/eprints3/bin/../perl_lib/EPrints/Database.pm line 1185.
=== Reason for error ===
Many of the <code>eprint</code> data object fields are set to type text, which leads to then being created as <code>VARCHAR(255)</code> columns in the <code>eprint</code> table in the archive's MySQL database. A <code>VARCHAR(255)</code> MySQL column can take up to 768 bytes of the maximum permitted 8126 bytes. 768 bytes are potentially required as each character in standard UTF-8 encoding takes three bytes. However, if a <code>VARCHAR</code> is empty it will only require 1 byte and more often than not it will only sue a fraction of the characters available. Unfortunately, this means if there is an unusual <code>eprint</code> record that uses a lot of characters in a lot of fields then it can result in an error like the one above. This becomes more likely to occur as additional fields are added to the <code>eprint</code> for bespoke requirements of the archive.

The reason for EPrints creating so many <code>VARCHAR(255)</code> MySQL columns is due to fields of type <code>text</code> added to a data object being created as <code>VARCHAR(255)</code> MySQL columns rather than <code>TEXT</code>. There are various differences between the types of MySQL columns, most noticeably <code>TEXT</code> can store up to 65535 characters rather than just 255. To facilitate storing more characters it stores these as a reference rather than in the row itself and therefore only use two bytes for this reference, using up a lot less space in the row than a <code>VARCHAR(255)</code> if this contains a long string of characters. However, there are a number of downsides to using a <code>TEXT</code> MySQL column:
# No default value other than <code>NULL</code> can be set. This does not affect EPrints as any requirement for default values is captured in its Perl-based configuration.
# The column is not fully indexed. This may affect how efficiently EPrints can carry our MySQL queries that are determinant on the value of this column. However, when EPrints creates new fields it typically creates an independent index, unless the field's <code>sql_index</code> attribute is set to 0.
# A slightly increased latency on recovering data via the reference. This would have no noticeable effect on the responsiveness of EPrints.

=== Resolution ===
Currently the only way to fix this problem is to manually modify various <code>VARCHAR(255)</code> columns in the <code>eprint</code> and make them <code>TEXT</code> or possibly <code>TINYTEXT</code> that would make them the same length as the original <code>VARCHAR(255)</code> column. The columns you should choose are those most likely to use a large number of characters. This may include fields like <code>publication</code>, <code>book_title</code> <code>id_number</code>, <code>event_title</code>, <code>publisher</code>, <code>contact_email</code>, <code>series</code>, <code>department</code>, <code>institution</code>, <code>place_of_pub</code> and <code>event_dates</code>.

One potential issue with doing this is that if you were to recreate the database (say on a test instance of your repository), these fields would be recreated as <code>VARCHAR(255)</code> rather than <code>TEXT</code>. Currently, there is no way to define a field in EPrints that will create a MySQL <code>TEXT</code> column. Therefore, for simplicity it may be easier to change the attribute type of these field to <code>longtext</code> (e.g. <code>type => 'longtext'</code>) in the EPrints configuration for this field, even though this allows text strings over 4 million characters long (although UTF-8 encoding would only allow strings up to a third of this length). To complete this change you would also need to manually run the following MySQL command to update the MySQL table column, e.g.
ALTER TABLE eprint MODIFY COLUMN publication LONGTEXT DEFAULT NULL;
If you modify the type of MySQL column in the <code>eprint</code> table it would also be sensible to make sure that the equivalent column in the <code>eprint__ordervalues_en</code> (and other <code>eprint__ordervalues</code> tables if your archive supports multiple languages) is also updated to use <code>LONGTEXT</code>. (Although this is likely to be the case, unless the particular field was added to the archive some time ago).
ALTER TABLE eprint__ordervalues_en MODIFY COLUMN publication LONGTEXT DEFAULT NULL;

As the example error messages says above, an alternative resolution to this problem could be to change the <code>ROW_FORMAT</code> to <code>DYNAMIC</code> or <code>COMPRESSED</code>. However, (and assuming you are using [[Converting_MyISAM_tables_to_InnoDB|<code>InnoDB</code>]] as the MySQL table engine), to do this you need to have the MySQL configuration parameters <code>innodb_file_format</code> and <code>innodb_file_format_max</code> needs to be set to <code>Barracuda</code> rather than <code>Antelope</code>. <code>Barracuda</code> does not become the default until MySQL 5.7 but earlier versions of MySQL should still support MySQL 5, so you can change to <code>Barracuda</code> by setting the following configuration settings under the <code>[mysqld]</code> section of <code>/etc/my.cnf</code> and restart MySQL:
innodb_file_format=Barracuda
innodb_file_format_max=Barracuda
innodb_large_prefix=1
You can then alter the table to change the <code>ROW_FORMAT</code> as follows:
ALTER TABLE eprint ROW_FORMAT=DYNAMIC;
Using <code>COMPRESSED</code> rather than <code>DYNAMIC</code> maybe useful for particularly large (multi-gigabyte) tables but there may be a performance trade-off to doing so. Therefore, if there is not a disk space constraint, <code>DYNAMIC</code> is probably the better choice.

If you use <code>ROW_FORMAT=DYNAMIC</code> you may still get the original "Row size too large" error message if you have more than 196 <code>LONGTEXT</code> columns whilst using certain versions of MySQL (e.g. 5.7). If your repository has added a lot of bespoke fields for the eprint data object, there is a fair chance your <code>eprint__ordervalues_en</code> will be close to this 196 limit on <code>LONGTEXT</code> columns.

It is likely that the eprint database tables will still include a number of fields that were created, never used and their definitions removed from the repository's configuration. If this is the case, this may help alleviate the problem of hitting this 196 <code>LONGTEXT</code> columns limit, as these fields can be manually removed from the eprint database tables. It is probably best to focus on removing single and non-compound rather than multiple compound fields, as the process to remove these is more straightforward. In the examples below the field to remove (or column to drop) is called '''unused''':
ALTER TABLE eprint DROP COLUMN unused;
ALTER TABLE eprint__ordervalues_en DROP COLUMN unused;
If you want to remove a multiple (non-compound) field the MySQL commands are more like:
DROP TABLE eprint_unused;
ALTER TABLE eprint__ordervalues_en DROP COLUMN unused;
If it is a multiple and compound field the MySQL commmands will probably be something like:
DROP TABLE eprint_unused;
ALTER TABLE eprint__ordervalues_en DROP COLUMN unused_subfield1;
ALTER TABLE eprint__ordervalues_en DROP COLUMN unused_subfield2;

== Data length too long for column ==
=== Example error message ===
DBD::mysql::st execute failed: Data too long for column 'volume' at row 1 at /usr/share/eprints/perl_lib/EPrints/Database.pm line 1187.

=== Reason for error ===
This is due to a field for a data object having its <code>maxlength</code> attribute increased but this will not have updated the size of the <code>VARCHAR</code> column in the MySQL table for the data object. The error message will appear in the webserver (e.g. Apache) error logs when a user sets a value that is longer than the original <code>maxlength</code> attribute value for a field. In the example error message above this is where the <code>volume</code> field for the <code>eprint</code> data object has been increased from its default <code>maxlength</code> of 6 to a higher value.

=== Resolution ===
To fix this issue you will need to manually modify the affected MySQL column. In the example error message above, if we assume you updated the <code>maxlength</code> attribute for the <code>volume</code> field of the <code>eprint</code> data object from 6 to 9, you will need to manually run the following MySQL command to update the database to correspond with the EPrints configuration for this field:
ALTER TABLE eprint MODIFY COLUMN volume VARCHAR(9) DEFAULT NULL;

Ideally running <code>epadmin update ARCHIVEID</code> would update fields to effect changes to attributes like <code>maxlength</code>. Unfortunately, due to the extensive number or scenarios of how fields could be changed, implementing robust ways that will reliably modify MySQL columns, whilst ensuring data is not lost or worse tables becoming corrupted or inconsistent, is a very complex task. However, writing a script to do a consistency check between the field configuration for EPrints data objects and the structure of these tables in the MySQL database for the archive [https://github.com/eprints/eprints3.4/issues/163 is being investigated].

== Too many keys specified ==
=== Example error message ===
#1069 - Too many keys specified; max 64 keys allowed

=== Reason for error ===
The above error message will occur when running <code>EPRINTS_PATH/bin/epadmin update ARCHIVEID</code>. By default current versions of MySQL installed by Linux package managers (e.g. YUM, APT, etc.) only allow 64 keys per MySQL database table. A key is added when a <code>CREATE INDEX</code> command is run and EPrints will do this for each new field added to a data object where the <code>sql_index</code> attribute is set to 1. However, as the generic default value for this attribute is 1, only if a specific type of field sets this default value to 0, will a field be created without an index. This is the case for <code>text</code>, <code>longtext</code>, <code>keywords</code>, <code>secret</code> and <code>storable</code> type fields and their sub-types. However, this is not the case for other types, which is in most cases appropriate, as it cannot take into account in what way and how frequently the field will be used and therefore if the MySQL column would really benefit from an index.

The reason <code>sql_index</code> has the generic default value of 1 is that having a field indexed should speed up database queries, particularly when results need to be ordered. It was felt it was unlikely that repository system administrators would explicitly set the <code>sql_index</code> to 1 for new fields they would be creating, as they may not appreciate the reasons for doing so. Therefore, a lot of fields that would benefit from an index could have ended up not getting one. However, particularly with highly bespoke EPrints archives, the number of columns that require indexes in the <code>eprint</code> MySQL table has grown close if not beyond the limit of 64 keys, prompting the error message shown above.

=== Resolution ===
There is a two-fold approach to this. One part if to change the EPrints field configuration and set the <code>sql_index</code> attribute to 0 for types of field that have this set to 1 by default. However, this will only be useful on the fields that are complained about when running <code>epadmin update</code>, as their indexes will not have been created due to the limit being reached and therefore you would just be removing the need for them being created. However, some of these new fields may benefit from having indexes but some existing fields may not or at least benefit significantly less. The best way to determine this is to look at the existing indexes for the MySQL table for the particular data object, typically <code>eprint</code>. The following MySQL command can retrieve this information:
SHOW INDEX FROM eprint;
Then there are a number of considerations about which fields could do without an index. Generally, those that store numerical values where comparisons are required greatly benefit from an index, so date/time fields like <code>datestamp</code>, <code>lastmod</code> and <code>date</code> greatly benefit from an index, especially as it combines the six separate MySQL columns that make up these EPrint fields (i.e. year, month, day, hour minute and second). The fields that are less important to have index are the ones that are sparsely used, so fields specific to a particular type of eprint that is not commonly used. A rough guide is that if the field is used in your archive's advanced search or staff search for eprints, then you would not want to remove its index.

The following standard <code>eprint</code> fields fit into the category of non-numeric and/or sparsely used, roughly in ascending order or use: <code>gscholar_cluster</code>, <code>gscholar_impact</code>, <code>template</code>, <code>pedagogic_type</code>, <code>num_pieces</code>, <code>succeeds</code>, <code>importid</code>, <code>monograph_type</code>, <code>sword_depositor</code>, <code>thesis_name</code>, <code>thesis_type</code>, <code>event_type</code>, <code>pres_type</code> and <code>contact_email</code>. However, the reason you will have hit your limit of keys is due to non-standard fields that will have been added to the archive so it is worth reviewing which of these are used sparsely and do not contain numeric values that are likely to have comparators or other mathematical operations applied to them.

Once you have identified the fields that least need indexes as well as setting the <code>sql_index</code> attribute for the field to 0 (and reloading the webserver and EPrints indexer), you will need to make sure the index has been dropped from MySQL itself. Using a MySQL command like the following:
DROP INDEX gscholar_cluster_0 ON eprint;
You will note that the index will have a slightly different name to the field. You should the <code>SHOW INDEX</code> MySQL command above to determine the correct name for the index. After doing this you should be able to add new fields without seeing the "Too many keys" error message. However, be sure to set <code>sql_index</code> to 0 on new fields you add if they are of a type that creates an index but you expect them to be sparsely used.

== Duplicate entry for key ==
=== Example error message ===
DBD::mysql::st execute failed: Duplicate entry '99288-1' for key 'PRIMARY' at /opt/eprints3/perl_lib/EPrints/Database.pm line 1287.

=== Reason for error ===
'''To be written'''
=== Resolution ===
'''To be written'''

== Deadlock found when trying to get lock ==
=== Example error message ===
'''To be added'''
=== Reason for error ===
'''To be written'''
=== Resolution ===
'''To be written'''

== MariaDB order without limit on subquery ==
=== Symptom of error ===
'''To be written'''
=== Reason for error ===
'''To be written'''
=== Resolution ===
'''To be written'''

EPrints4 Status

2024-02-19T13:27:35Z

Th.lauke@arcor.de: link added

[[Category:Eprints4]]
[[Category:Contribute]]

Packages that are considered "CORE": [[EPrints4_CORE]]

Things which have been tested / implemented:

=CORE=

==Database==

* Preferred MySQL engine is now [[Converting_MyISAM_tables_to_InnoDB|InnoDB]] (over MyISAM)
* Added support for transactions with InnoDB. Partially written data/data-objects may be roll-backed (they are if an error occurs)
* Connects on demand

==Request handlers/routers==

* Every request is now routed via a trigger call (to find out which controller will respond)
* Apache::Rewrite has been refactored to Apache::Handler and is now super-lightweight
* Support for CGI scripts has been removed

==Controllers==

* CRUD
* Storage (delivery of files/thumbnails)
* Counter (like /cgi/counter)
* Ping (for fun, just replies 'pong')
* UI (for, potentially, Screen plug-ins)
* Static pages (XHTML, XPAGES etc that need compilation to HTML or any other static file (js, css...)

==Security==

* Based around actions (e.g. edit, view, search, ...) and optional contexts ('owner', etc.)
* Low-level implementation to avoid objects to leak from one dataset ('inbox') to another ('archive')
* ACL dataset (should maybe be called 'privs') to store extra privs against a user
* finer-grain permission (down to a single dataobj)

==Auth==

* Rewritten auth mechanisms
* Done similarly to Controllers, via a trigger
* When a user is auth'ed a user-session is created (cf. login ticket)
* When a request comes, EPrints attempts to load a user-session - cf. above
* Supports AuthBasic when no UI is available
* Cookies are managed transparently behind the "user-session"

==Storage==

* Added support for generic files. It is now possible to store any file against any object.
* Added support for "thumbnails" (as a separate dataset)

==CRUD==

* CRUD extended to support more methods/URI etc
* Sword2 hacks temporarily removed from CRUD
* Doesn't require its own auth code anymore
* CrudClient available to perform remote operation on a repository (via CrudDataSet, CrudDataObj, CrudList etc) - the API is very similar to the standard CLI syntax to create/edit/etc objects/lists of objects.
* Support for ETag and If-None-Match
* Support for PATCH method
* Support for generic file upload
* Minimal support for searching a dataset (e.g. GET /data/user/) - though will probably have a separate /search/... interface to allow user queries (Xapian and the likes)
* Entry poing /id/... moved to /data/...

==Dataset definition==

* The following properties are now core (meaning that EPrints will automatically add appropriate fields, set/update/remove data when such or such properties are enabled):
** flow: replaces eprint_status and the likes. Allows to specify a flow of states and transitions
** revision: adds a revision number, incremented each time the data obj is modified
** acl (TO RENAME): allows ACL checks on the dataset (should always be ON)
** read-only: make the dataset read-only, no modifications are allowed via the API (whether HTTP, CLI ...)
** web-read-only (TOFIX): make the dataset read-only ONLY for HTTP requests - CLI scripts can still change data
** history (TODO): keeps an historic of changes
** lastmod: keeps a timestamp of when the data-obj was last modified
** datestamp: keeps the date of creation of a data-obj
** loghandler (TODO): keeps download stats for that dataset
** contexts: allows to add custom security contexts (eg. 'owner', 'editor', 'co-author')

==Misc==

* memcached: use of server-wide "memcached" service to memory cache data objects
* contextual debugging: allows to enable/disable only specific themes e.g. "db", "security" etc. and only write status messages to the logs for the enabled themes
* much, much more!

=UI=

* Template using Bootstrap
* Data-binding with JS Framework AngularJS
* Dynamical pages served through light-weight Screen plug-ins (only handles the security aspect - who can see this page - and the "page's actions" via AJAX)

EPrints and MySQL 8

2024-02-19T13:26:07Z

Th.lauke@arcor.de: link added

Various changes have been made to MySQL between version 5.7 and 8 and these can have some impact on EPrints.

== Slow Performance ==
By default EPrints now uses [[Converting_MyISAM_tables_to_InnoDB|InnoDB]] as its table engine. As EPrints can make a lot of transactions to update a eprint record whilst in the workflow, as well as complex background tasks this means the default configuration of MySQL makes EPrints rather slower than before. This can be fixed by adding the following line to <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt>:
innodb_flush_log_at_trx_commit=2
What this change does is ensure the logs are flushed once a second rather than after each transaction commit. This is not ideal as your bin logs could potential miss transactions if the database was to crash but does significantly improve the performance of EPrints. Further investigation is required to determine how serious an impact lost transactions from the bin logs would be for EPrints. At worse this would likely affect only a small number of eprints.

== Not Null without Default Value ==
In EPrints a MetaField can set the attribute <tt>allow_null => 0</tt>. This means strictly it has to have a default value. Prior to EPrints 3.4.4, default values were not set for MetaField's created with <tt>allow_null => 0</tt> and not [https://github.com/eprints/eprints3.4/issues/196 until EPrints 3.4.5] were the default values tailored depending on the type of database field. MariaDB 10 also has the same issue.

If you are running an earlier version of EPrints, you could manually alter your database to ensure that any MetaFields that have <tt>allow_null => 0</tt> and set a default value something like:
ALTER TABLE `eprint` MODIFY COLUMN `not_null_field` VARCHAR(255) NOT NULL DEFAULT '';
Otherwise, you could change your MySQL server's configuration to overlook this by adding the following to <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> (and affectively removing the part of <tt>STRICT_TRANS_TABLES</tt> that causes this to error). Once done remember to restart MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION

== Data Too Long for Field ==
EPrints often uses <tt>VARCHAR(255)</tt> fields. This can sometime present a problem especially if the text contains special characters which in affect makes the column even less than 255 characters. Previously MySQL has just truncated data that has got to long but in MySQL 8 (as well as MariaDB 10) it now just throws and error message.

The main place in EPrints this is a problem is indexing metadata and the full text of documents. Since [https://github.com/eprints/eprints3.4/issues/247 EPrints 3.4.5], a restriction on the max length of a word that can be indexed has been added to restrict this to 128 characters, this ensures that even if special characters are used the total space required to store the string does not exceed that available to a <tt>VARCHAR(255)</tt> by some margin.

However, if you are running an earlier version of EPrints, the only solution for now is the same as for the "[[#Not Null without Default Value|Not Null without Default Value]]" issue and setting the SQL mode in <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> as follows and then restarting MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
Like this other issue it is <tt>STRICT_TRANS_TABLES</tt> that will throw an error rather than quietly truncate, which although also not ideal is generally less problematic. As terms that are too longer are unlikely ever to be those searched.

== Deprecation Warnings ==
Some of the more recent versions of MySQL state that some of the options in <tt>sql_mode</tt> have been deprecated. In particular: <tt>NO_ZERO_IN_DATE</tt>, <tt>NO_ZERO_DATE</tt> and <tt>ERROR_FOR_DIVISION_BY_ZERO</tt>. Therefore, you should additional remove these to leave SQL mode in <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> looking like:
sql_mode=ONLY_FULL_GROUP_BY,NO_ENGINE_SUBSTITUTION

[[Category:Installation]]

Log Files

2024-02-19T13:23:02Z

Th.lauke@arcor.de: login log added

[[Category: Work in Progress]]
[[Category: FAQ]]
[[Category: Management]]

EPrints produces a number of log files, as do the integral components of EPrints such as Apache and MySQL. Below is a list of logs files that may be of interest for debugging EPrints. (Please note that log files may appear in different place for different operating systems):

{| class="wikitable"
|-
! Name
! Typical Location on Red Hat based Linux
! Typical Location on Debian based Linux
! Purpose
! Uses
|-
! Apache access log
| /var/log/httpd/access_log
| /var/log/apache2/access.log
| Logs all accesses to HTTP URLs hosted by Apache unless an individual access log has been created for a particular "virtualhost".
| Can be searched over to check IP addresses that are making excessive or malicious requests.
|-
! Apache error log
| /var/log/httpd/error_log
| /var/log/apache2/error.log
| Logs all issues that occur with Apache or underlying application (i.e. perl and mod_perl) when attempting to service URL requests.
| Can be used to debug issues with EPrints code base, where a script cannot or behaves normally when run directly from the command line.
|-
! Apache ssl access log
| /var/log/httpd/ssl_access_log
| /var/log/apache2/ssl_access.log
| Logs all accesses to HTTPS URLs hosted by Apache unless an individual access log has been created for a particular "virtualhost".
| Can be searched over to check IP addresses that are making excessive or malicious requests for HTTPS URLs.
|-
! Apache ssl error log
| /var/log/httpd/ssl_error_log
| /var/log/apache2/ssl_error.log
| Logs all issues that occur with Apache or underlying application (i.e. perl and mod_perl) when attempting to service HTTPS URL requests.
| Can be used to debug issues with EPrints code base, where a script cannot or behaves normally when run directly from the command line.
|-
! MySQL log
| /var/log/mysql/mysql.log or /var/log/mariadb/mariadb.log
| /var/log/mysql/error.log
| Logs general operational issue about MySQL and any errors that occur with the application but not specific database queries
| Only really useful if MySQL / MariaDB will not start properly.
|-
! EPrints indexer log
| EPRINTS_PATH/var/indexer.log
| EPRINTS_PATH/var/indexer.log
| Logs information and error messages generated by the EPrints indexer that is used to schedule more processor intensive tasks to ensure EPrints itself remains responsive
| To find out why tasks in your event queue (see http://EPRINTS_HOSTNAME/cgi/users/home?screen=Listing&dataset=event_queue) have failed.
|-
! EPrints openoffice log
| EPRINTS_PATH/var/openoffice.log
| EPRINTS_PATH/var/openoffice.log
| If you have the Coversheets plugin installed it logs information and error messages generated by OpenOffice that runs to generate coversheets to stitch onto the front of uploaded PDF documents
| This file only really logs issues with OpenOffice general running not specific issues cover-sheeting a particular document. The EPrints indexer log will more likely contain this information.
|-
! EPrints login attempts log
| EPRINTS_PATH/archives/ARCHVEID/var/login_attempts/yyyy/mm/dd.csv
| EPRINTS_PATH/archives/ARCHVEID/var/login_attempts/yyyy/mm/dd.csv
| Logs all issues that occur due to login attempts.
| Can be used to debug issues with failing or erroneous logins.
|}

== Parsing the Apache access log ==
:
...

EPrints 3.4 and PostgreSQL

2024-02-19T13:08:03Z

Th.lauke@arcor.de: categories added

{{Work in Progress}}
[[Category:Work in Progress|Deprecated]]
EPrints has supported PostgreSQL since quite early in its development. However, MySQL is the default database engine, so few repositories actually use PostgreSQL. This page examines how to setup the latest version of EPrints 3.4 (currently 3.4.2) using PostgresSQL.

== Installiing and Configuring PostgreSQL ==
'''This is based on installing on a CentOS 7 Linux operating system.'''
Carry out the following steps as the ''root'' user.
1. Install the required packages using YUM:
yum install postgresql postgresql-server perl-DBD-Pg
2. Perform initial PostgreSQL setup
postgresql-setup initdb
3. Edit ''/var/lib/pgsql/data/pg_hba.conf'' by changing the following two lines to allow password-less local access and access from localhost (i.e. when using ''--host localhost'' flag with ''psql''):
local all all peer
host all all 127.0.0.1/32 ident
to
local all all trust
host all all 127.0.0.1/32 trust
You may wish to set authentication option to ''md5'' rather than ''trust'' to restrict access for some users on your server but you will need to manual set a password for the ''postgres'' user.

4. Enable and start PostgreSQL on the operating system
systemctl enable postgresql
systemctl start postgresql

== Creating an EPrints archive with a PostgreSQL database ==
'''To be written...'''

Installing Oracle

2024-02-19T13:07:00Z

Th.lauke@arcor.de: categories modified

{{Work in Progress}}
[[Category:Work in Progress|Deprecated]]
Oracle support hasn't been fully tested yet.

Added in version 3.1.0.

== Requirements ==

* An Oracle database with an account that has full privileges
* Oracle database client
* [http://search.cpan.org/~pythian/DBD-Oracle-1.21/ DBD::Oracle]

You should set the Oracle table character coding to "utf-8".

== Installing Oracle Express Edition ==

This is only required if you wish to use the free Oracle DB for testing/development purposes.

See [https://help.ubuntu.com/community/Oracle Oracle on Ubuntu].

== Adding Oracle Environment Variables ==

Make life with Oracle easier by adding the Oracle environment variables to the global system profile.

Create /etc/profile.d/oracle.sh (replace 10.2.0 with the correct version for your Oracle server/client):

ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server
ORACLE_SID=XE
PATH=$PATH:$ORACLE_HOME/bin
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib
export ORACLE_HOME
export ORACLE_SID
export PATH
export LD_LIBRARY_PATH

You will need to log out/in for this change to take effect.

== GQLPlus ==

The sqlplus tool has very poor shell support. For a better shell tool use [http://gqlplus.sourceforge.net/ gqlplus].

== Installation ==

Install EPrints as normal but don't create a (MySQL) database.

Edit archives/[repoid]/cfg/cfg.d/database.pl to add the Oracle configuration:

#$c->{dbname} = 'eprints';
#$c->{dbhost} = 'localhost';
#$c->{dbport} = undef;
#$c->{dbsock} = undef;
$c->{dbdriver} = 'Oracle';
$c->{dbhost} = 'localhost';
$c->{dbsid} = 'XE';
$c->{dbuser} = 'HR';
$c->{dbpass} = 'HR';

dbsid is the name of the Oracle database.

Create the database and import subjects:

./bin/epadmin create_tables [repoid]
./bin/import_subjects [repoid]
./bin/epadmin create_user [repoid]

Continue configuring EPrints.

== Troubleshooting ==

Depending on your server configuration you may find you need to set environment variables for DBD::Oracle to find your Oracle client:

export ORACLE_SID=XE
export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server

At the moment starting the indexer from the Admin page doesn't work, due to the Oracle environment variables not being present.

=== ORA-24327: need explicit attach before authenticating a user ===

Make sure you have set $c->{dbhost}.

Display a custom response during downtime

2024-02-19T12:46:30Z

Th.lauke@arcor.de: typos removed, some reformatting

[[Category:Howto]]
[[Category:Management]]

See also [[Creating a Maintenance Page]].

We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.

During this downtime, I wanted to display a useful message, with a '503 Service unavailable' HTTP response.
This is how to achieve this using EPrints triggers:

'''NOTE''' if you are doing maintenance blocking the database, the '''method below will not work, as EPrints will complain about not being able to connect to the database''' before processing the trigger. If your maintenance will result in the database being offline (rather than read-only), the maintenance page should be delivered using Apache. Please see https://stackoverflow.com/questions/622466/how-to-put-apache-website-to-503-temporary-down for some examples).

# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.
# Add the following to the file, altering the <code>maintenance_allowed_ip</code>, <code>maintenance_retry_after</code> and <code>maintenance_page_html</code> including <code>###REPO NAME###</code>, <code>Date/Time</code> and contact e-mail address appropriately. I'd keep the html page quite simple, but with enough info to help a human. Remember to '''escape any single-quotes''' in the HTML block with a backslash e.g. ''BAD'': <code>we've</code>; ''GOOD'': <code>we\'ve</code>.:
<source lang="perl">
# Set maintenance to 1 to respond with a 503 for requests, except those from the maintenance_allowed_ip.
$c->{maintenance} = 0;
$c->{maintenance_allowed_ip} = '127.0.0.1'; #set this to your IP address

# set to a date/time after your maintenance will have finished,
# or a period (in seconds) that the maintenance will last for
$c->{maintenance_retry_after} = 'Mon, 14 Mar 2016 12:00:00 GMT'; #set to a date/time after your maintenance will have finished

use EPrints::Const;
$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %args ) = @_;

# args passed to EP_TRIGGER_URL_REWRITE are:
# request, lang, args, urlpath, cgipath, uri, secure, return_code
my( $repository, $request, $return_code, $uri, $urlpath ) = @args{ qw( repository request return_code uri urlpath ) };

#check we're in maintenance mode
if( $repository->config( "maintenance" ) && $repository->config( "maintenance" ) == 1 ){
# is there an IP we should allow through?
# NB You might need to do other checks - e.g. X-Forwarded-For if you are behind a load-balancer
# or for different versions of Apache (like here: https://github.com/eprints/eprints/issues/214)
# if you're not sure, ask on the EPrints Tech list first!
if( $repository->config( "maintenance_allowed_ip" ) &&
$repository->remote_ip eq $repository->config( "maintenance_allowed_ip" ) ){
return EP_TRIGGER_OK;
}
elsif( $uri !~ /^$urlpath\/(style|images)\// ) # allow image/stylesheet requests
# through - so you can display a branded 503 page
{
$request->custom_response( Apache2::Const::HTTP_SERVICE_UNAVAILABLE, $c->{maintenance_page_html} );
if( $repository->config( "maintenance_retry_after" ) ){
$request->err_headers_out->{'Retry-After'} = $repository->config( "maintenance_retry_after" );
}
# set the 503 response
${$return_code} = EPrints::Const::HTTP_SERVICE_UNAVAILABLE;
# and don't process any more EP_TRIGGER_URL_REWRITE triggers.
return EP_TRIGGER_DONE;
}
}
} );

# A simple maintenance page - not using the template (which will probably link to various other pages that aren't
# accessible during the maintenance window
$c->{maintenance_page_html} = '<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style>
body {
font-family: sans-serif;
margin: 3em;
}
footer {
font-size: 80%;
margin-top:2em;
}
</style>
<title>###REPO NAME### - Maintenance</title>
</head>
<body>
<header>
<img src="/images/sitelogo.png" />
<h1>###REPO NAME### - Maintenance</h1>
</header>
<section>
<p><strong>Date/Time</strong> We\'re currently doing things to the system.<br />
We\'ll be back soon!</p>
<p>If you have any questions, please contact someone@somewhere.blah</p>
</section>
<footer>
<p>###REPO NAME###</p>
</footer>
</body>
</html>';

</source>

# Do a <code>~/bin/epadmin test ARCHIVEID</code> to make sure you haven't done anything silly in the config file.
# Do a <code>~/bin/epadmin reload ARCHIVEID</code> and check that nothing's changed
# When you want to turn the maintenance response on, change set: <code>$c->{maintenance} = 1;</code> and reload the archive.
# Check that you can get in from the IP specified, and that you get the 503 response from other IPs.
# Do a graceful restart of Apache (e.g. <code>apachectl graceful</code>) - to stop the noisy 'repository had been reloaded' error messages.
# Do the maintenance.
# Change <code>$c->{maintenance} = 0;</code>, graceful restart Apache (e.g. <code>apachectl graceful</code>).
# Done!

If you want to include the default CSS files in the 503 page, include <code><link rel="stylesheet" type="text/css" href="/style/auto-3.3.14.css"></code> in the maintenance_html_page -> head section (update it for your version of EPrints!).

Required software

2024-02-19T11:53:11Z

Th.lauke@arcor.de: links added, formatting harmonized

{{manual}}
[[Category:Installation]]

==What Additional Software does EPrints Require?==

In brief, EPrints minimally requires Apache (with mod_perl), MySQL and Perl with some extra modules. Various utilities like wget, tar and unzip would also be useful.

EPrints bundles some [https://github.com/eprints/eprints3.4/blob/master/cpan_modules.pl Perl modules] which it uses, to save you installing them.

==Where to get the Required Software==
Apache, MySQL, Perl and mod_perl are all provided as operating system level packages that can be installed on EPrints' [[Recommended Platforms]]. If you wish to install on a platform that is not recommended, then you will need to determine the best way to install these applications. It may be possible to infer comparable packages for your platform by checking the dependencies installed on [[Installing EPrints on RHEL/Fedora/CentOS|Red Hat based]] and [[Installing EPrints on Debian/Ubuntu|Debian based]] Linux.

==Other Tools==

===File uploads===
<tt>wget</tt>, <tt>tar</tt>, <tt>gunzip</tt> and <tt>unzip</tt> are required to allow users to upload files as <tt>.tar.gz</tt> or <tt>.zip</tt> or to capture them from a URL.

These all come installed with most modern versions of linux. If you cannot get them working, you can remove the relevant option by editing "archive_formats" in <tt>SystemSettings.pm</tt>

If there are problems you may need to tweak how these are invoked in <tt>SystemSettings.pm</tt>.

===Full Text Indexing===
The EPrints indexer requires various tools to extract plain (UTF-8) text from different types of document for indexing.

The full text indexer requires various tools to index each kind of document. These tools may or may not be already installed in your system. EPrints uses these tools to build a "words" file for each document (which contains the text of the document in UTF-8). If it can't run the tool, the "words" file will be empty and EPrints will not retry creating it unless you manually remove it.

====PDF====
Full text indexing PDF documents requires <tt>pdftotext</tt> application provided by the ''poppler-utils'' Deb or RPM package.

====Microsoft Word====
Full text indexing of Microsoft Word documents is provided by the ''antiword'' Deb or RPM package. The RPM package is available through the [https://forensics.cert.org/cert-forensics-tools-release-el7.rpm forensics] RPM repository.

====HTML====
Full test indexing of HTML documents requires the <tt>lynx</tt> text-based browser provided by the ''lynx'' Deb or RPM package.

===LaTeX Tools===
There is an optional feature which allows you to instruct EPrints to look in certain fields (e.g. title and abstract) for strings that look like LaTeX equations and render them as images. These tools are only required if you want to use this feature.

These are provided by the ''tetex-latex'' and ''ImageMagick'' RPMs or the ''texlive-base'', ''texlive-bin'' and ''imagemagick'' Deb packages.

This is a "cosmetic" feature, it only affects the rendering of information, so you can always add it later if you want to save time initially.

==Other Platforms==
Often the best way to find certain packages of other platforms is to use a search engine to look for the package name for Red Hat or Ubuntu Linux along with the name of your platform. (E.g. antiword Arch Linux). If you platform does not have comparable packages, then the next best option is to download the software tool is the official site. Below are links to the download pages for the essential components of EPrints:
* [https://httpd.apache.org/download.cgi Apache]
* [https://dev.mysql.com/downloads/ MySQL] (or [https://downloads.mariadb.org/ MariaDB]) as well as [https://www.postgresql.org/download/ PostgreSQL] and even [https://www.oracle.com/de/downloads/ ORACLE]
* [https://www.perl.org/get.html Perl]
* [https://perl.apache.org/download/ mod_perl]

Template:EPrints-tech Archive

2024-02-19T10:32:47Z

Th.lauke@arcor.de: updated

To view the archives of the list go to https://www.eprints.org/eptech/

'''January 2024 update''': Updating with the latest posts to the list and searching is back again, but we are still working on a better structured list archive to make it easier to get an overview.

Main Page

2024-02-19T09:58:51Z

Th.lauke@arcor.de: link added

[[Category:Howto]]__NOTOC__
= Welcome to the EPrints Wiki =

This wiki contains technical and user-contributed documentation for the [[Introduction|EPrints repository software]].

[http://tryme.demo.eprints-hosting.org/ Demoprints] is our live, online server that allows anyone to try EPrints without having to install it first. There are also [http://demo.eprints-hosting.org examples] of various 'flavours' of EPrints available to view as well as some more information on the [https://eprints.org/ EPrints project] and related activities.

==New to EPrints?==

Found out more through our:
* [[EPrints Glossary]] - Descriptions of the terminology used within EPrints repository software.
* [[:Category:Training Video|Video Training Course]]
* [[EPrints_Manual|Documentation]]
* [[Working Groups]]
* Mailing lists - There are two mail lists that you might like to join and where you can ask for help and share ideas:
** '''[[eprints-tech Mailing List|The EPrints Technical Mailing List]]'''
*** If you have technical questions, or a part of your EPrints installation is not working properly, this group has people who might be able to help!
*** [[eprints-tech Mailing List|Click here]] for information about [[eprints-tech Mailing List#Subscription_Options|subscribing to this list]] or [[eprints-tech Mailing List#List_Archives|reading its archives]].
** '''[https://groups.google.com/forum/#!forum/eprints-uk-user-group The EPrints User Group Google Group]'''
*** This group is for anyone involved in using EPrints. Ask questions, share ideas, hear about forthcoming meetings.
* How to [[Main_Page#Contributing_to_the_Wiki|contribute to the EPrints wiki]]
* EPrints source code on GitHub:
** Core and major plugins - https://github.com/eprints
** Community code sharing - https://eprintsug.github.io and the repositories at https://github.com/eprintsug

== Download EPrints ==

{{Download}}

==Installation==

* [[:Category:Installation|Installing]] EPrints on various platforms

==[[New_Repository | Getting Started]]==

* [[EPrints Manual|EPrints 3 Documentation]]
* [[Perl 101 for EPrints]]
* [https://www.eprints.org/software/training/ Training materials] provided by EPrints Services.
* [[Frequently Asked Questions]]
* [[:Category:Howto|How to ...]]
* [[:Category:Plugins|Plugins and Bazaar packages for EPrints]]
* [[:Category:Training Video|EPrints Training Course]]

==Getting Support==

* [https://www.eprints.org/services/ EPrints Services] - premium support, training and hosting from EPrints experts
* [[Contact]] - mailing lists, bug reports etc.
* [[User group meetings]] - regional meetings for users, which often have notes, presentations and information of general interest

==Add-ons, patches and translations==

* As of version 3.3 EPrints can now install plugins and translations through the [https://bazaar.eprints.org EPrints Bazaar] the wiki also has information about [[:Category:EPrints Bazaar|packaging plugins for the Bazaar]].
* The [https://files.eprints.org/ EPrints Files Repository] contains add-on and 3rd party scripts, patches and translations. This also provides an archive of all previous EPrints releases (3.0 onwards).
* [[:Category:Plugins|Plugins]]: Some Wiki pages about scripts and patches.

{{Register}}

==Contributing to EPrints==

* [[Usability|EPrints usability]]
* New features in EPrints - [[:Category:Releases|released]] and [[:Category:Planned Releases|proposed]]
* [[How to contribute|How to contribute to EPrints development]]
* [https://github.com/eprints/eprints3.4 EPrints 3.4 on GitHub] - Codebase, releases and issues tracker for EPrints 3.4.
* [https://github.com/eprints/eprints3 EPrints 3.3 on GitHub] - Codebase, releases and issues tracker for EPrints 3.3 (legacy).

== Content management ==

* [[Digital preservation]]: managing content for longer-term access and use

Contact

2024-02-19T09:53:24Z

Th.lauke@arcor.de: link added

{{manual}}

==Bug Report Policy==

We use a [https://github.com/eprints/eprints/ Github] to record bugs and issues for EPrints. You can search there or the eprints-tech mailing list for existing bugs and possible solutions.

If you identify a new bug or "issue" (issues are not bugs, but are things which could be clearer or better) please post a message to the eprints-tech mailing list - include all the information you can: what version of eprints, operating system etc.

If you think the bug has security implications (i.e. it shouldn't be made public) please email [mailto:support@eprints.org support@eprints.org].

== [[eprints-tech Mailing List]] ==

[http://www.eprints.org/tech.php/ eprints-tech] is the mailing list for technical queries or feedback. It can also have general queries, but most traffic is of a technical nature.

{{EPrints-tech Subscription}}

For more options to manage your subscription to the eprints-tech list [[eprints-tech Mailing List#Subscription Options|click here]].

{{EPrints-tech Archive}}

== Twitter==

The following twitter accounts and hashtags are currently used:

* [http://twitter.com/EPrints @EPrints] - EPrints twitter account
* [http://twitter.com/EPrintsServices @EPrintsServices] - EPrints Services twitter account
* [http://twitter.com/hashtag/EPrints #EPrints] - EPrints Hashtag

== EPrints User Groups ==

For general or language dependent EPrints discussion

* [[German_User_Group|DE]]
* [https://groups.google.com/forum/#!forum/eprints-uk-user-group UK]

Eprints-tech Mailing List

2024-02-19T09:44:50Z

Th.lauke@arcor.de: typo removed

This page provides information about the eprints-tech.ecs.soton.ac.uk mailing list which is intended for those who develop and administer EPrints repository software.

== How to Subscribe ==
{{EPrints-tech Subscription}}

== Subscription Options ==
You can email [mailto:sympa@ecs.soton.ac.uk sympa@ecs.soton.ac.uk] with the following text in your subject line to carry out certain commands:
; INFO eprints-tech : Get information about the eprints-tech list.
; SUBSCRIBE eprints-tech ''your name'' : Subscription (or subscription confirmation) to eprints-tech.
; UNSUBSCRIBE eprints-tech ''email@address'' : Unsubscribe from eprints-tech. The email address is required only if you want to unsubscribe with an address other than the address with which you send the message.

The SET command allows you to change options for your current subscription to the EPrints Tech list.
; SET eprints-tech NOMAIL : suspend receipt of the eprints-tech's messages.
; SET eprints-tech DIGEST : receive messages in digest mode.
; SET eprints-tech DIGESTPLAIN : receive messages in digest mode (plain text).
; SET eprints-tech SUMMARY : only receive lists of messages.
; SET eprints-tech NOTICE : only receive the message subjects.
; SET eprints-tech MAIL : normal message delivery mode.

== List Archives ==
{{EPrints-tech Archive}}

History

2024-02-19T08:50:25Z

Th.lauke@arcor.de: updated

{{Manual}}
[[Category:Releases]]
==A Brief History of EPrints==
The EPrints project was created by Professor Stevan Harnad.

; '''May 25th 2023''' : [[EPrints 3.4.5]] released.
; '''August 7th 2022''' : [[EPrints 3.4.4]] released.
; '''April 27th 2021''' : [[EPrints 3.4.3]] released.
; '''July 11th 2020''' : [[EPrints 3.4.2]] released.
; '''April 5th 2019''' : [[EPrints 3.4.1]] released.
; '''May 4th 2018''' : EPrints 3.4 released.
; '''September 16 2011''' : EPrints 3.3 released.
; '''March 10 2010''' : GNU EPrints 3.2 released.
; '''September 8 2008''' : GNU EPrints 3.1 released.
; '''December 18 2006''' : GNU EPrints 3.0 RC-1 released.
; '''December 5 2006''' : GNU EPrints 3.0 Beta-3 released.
; '''November 14 2006''' : GNU EPrints 3.0 Beta-2 released.
; '''October 26 2006''' : GNU EPrints 3.0 Beta-1 released.
; '''July 25 2005''' : GNU EPrints 2.3.13 released.
; '''May 24 2005''' : GNU EPrints 2.3.12 released.
; '''March 8 2005''' : GNU EPrints 2.3.11 released.
; '''March 2 2005''' : GNU EPrints 2.3.10 released.
; '''February 17 2005''' : GNU EPrints 2.3.9 released.
; '''February 16 2005''' : GNU EPrints 2.3.8 released.
; '''November 25 2004''' : GNU EPrints 2.3.7 released.
; '''August 9 2004''' : GNU EPrints 2.3.6 released.
; '''August 6 2004''' : GNU EPrints 2.3.5 released.
; '''July 6 2004''' : GNU EPrints 2.3.4 released.
; '''March 4 2004''' : GNU EPrints 2.3.3 released.
; '''February 25 2004''' : GNU EPrints 2.3.2 released.
; '''February 5 2004''' : GNU EPrints 2.3.1 released.
; '''January 12 2004''' : GNU EPrints 2.3.0 released.
; '''October 31 2002''' : GNU EPrints 2.2 (Pumpkin) released. Added subject editors and GDOME support.
; '''July 4 2002''' : GNU EPrints 2.1 (Pineapple) released. Added subscriptions and OAI 2.0 support.
; '''July 1 2002''' : EPrints officially joins GNU Project.
; '''Apr 17 2002''' : EPrints 2.0.1 (Tuna) released. Mostly bugfixes.
; '''Feb 14 2002''' : EPrints 2.0 (Olive) released.
; '''Jan 2002''' : EPrints 2 Alpha-2 (Pepperoni) released.
; '''August 2001''' : EPrints 2 Alpha-1 (Anchovy) released.
; '''June 2001''' : Mike Jewell joins EPrints, working primarily on installer software
; '''January 2001''' : EPrints 1.1 released, contains OAI 1.0 support
Work begins on EPrints 2
; '''November 2000''' : EPrints 1.0 released, contains OAI 0.2 support
Rob Tansley leaves the EPrints Project
Christopher Gutteridge joins the EPrints Project
; '''September 2000''' : EPrints beta-2 released
; '''June 2000''' : EPrints beta-1 released
Cogprints archive created. http://cogprints.soton.ac.uk/
; '''April 2000''' : Rob Tansley begins work on EPrints
; '''October 1999''' : A turnkey repository platform promised by Stevan Harnad & Les Carr at initial OAI (UPS) meeting in Santa Fe.

Category:Releases

2024-02-19T08:25:53Z

Th.lauke@arcor.de: link added

This category is where information about the [[EPrints_3.4_Version_Codenames|EPrints releases]] are stored. You can find out about older releases and see what features will be in [[:Category:Planned_Releases |future releases]].

Template:EPrints-tech Subscription

2024-02-19T08:19:33Z

Th.lauke@arcor.de: links extended

To subscribe send an email with a blank message body to [mailto:sympa@ecs.soton.ac.uk?Subject=SUBSCRIBE%20eprints-tech%20yourGivenFamilyName sympa@ecs.soton.ac.uk] with the subject line:
SUBSCRIBE eprints-tech ''your name''
You do not have to provide your name, so <code>SUBSCRIBE eprints-tech</code> should be sufficient. You can provide a single name or multiple names but it is preferable to use the format of '''given name followed by family name''', e.g. ''Joe Bloggs''.

New Repository

2024-02-19T07:44:30Z

Th.lauke@arcor.de: links updated

Congratulations! You have successfully installed your EPrints repository.

* To learn how to customise features, view the [[Manual|EPrints Manual]] part of this wiki.

* The [[:Category:Howto|How-to Configure EPrints]] section is the mainly user generated documentation and contains pragmatic explanations of how to perform common repository configuration tasks. If you do something with your repository we don't have a tutorial for why not have a go at writing one.

* If you are a programmer looking to get started developing new features then you should look at the [[:Category:API|EPrints API]] and [[:Category:Plugins|EPrints Plugins]] documentation.

* For free help and advice on running, maintaining and developing your repository you can ask the [https://wiki.eprints.org/w/Eprints-tech_Mailing_List EPrints Tech mailing list] but do please have a quick search of the [http://www.eprints.org/tech.php/ list archive] before asking a question since you may find your answer there more quickly.

* If you need more help getting started, the [https://www.eprints.org/uk/index.php/about/meet-the-team/ EPrints team] has a [http://eprints.org/services/ commercial services arm] which provides training, support, hosting and consultancy services.

Category:Howto

2024-02-16T17:53:48Z

Th.lauke@arcor.de: typo removed

When you install EPrints there are a handful of tasks you will probably have to do for every repository you create. This section is designed to give each of those tasks a focal point. The documents found here are tutorial explanations of how to perform common tasks in EPrints. They are not designed to be comprehensive but they should give you a flavour of the sort of things that can be done. If you supplement the information here with the material in the [[:Category:EPrints_3_Reference]], then you should find you are able to achieve most of your goals.

If you run into any trouble you can always ask EP-Tech. {{EPrintsTech}} If you find one of the How-tos has a mistake or is out of date please feel free to add corrections that made it work for you.

If you end up doing something which is not yet documented here, feel free to make a page explaining what you did and how you did it. Commonly you will not have time in your day-to-day work to write a whole How-to, so instead why not try adding a '''"[[:Category:Snippets|snippet]]"'''?

[[Template:Register|Here you can register for an eprints.org account]] to edit the wiki.

Main Page

2024-02-16T17:48:30Z

Th.lauke@arcor.de: links updated

[[Category:Howto]]__NOTOC__
= Welcome to the EPrints Wiki =

This wiki contains technical and user-contributed documentation for the [[Introduction|EPrints repository software]].

[http://tryme.demo.eprints-hosting.org/ Demoprints] is our live, online server that allows anyone to try EPrints without having to install it first. There are also [http://demo.eprints-hosting.org examples] of various 'flavours' of EPrints available to view as well as some more information on the [https://eprints.org/ EPrints project] and related activities.

==New to EPrints?==

Found out more through our:
* [[EPrints Glossary]] - Descriptions of the terminology used within EPrints repository software.
* [[:Category:Training Video|Video Training Course]]
* [[EPrints_Manual|Documentation]]
* [[Working Groups]]
* Mailing lists - There are two mail lists that you might like to join and where you can ask for help and share ideas:
** '''[[eprints-tech Mailing List|The EPrints Technical Mailing List]]'''
*** If you have technical questions, or a part of your EPrints installation is not working properly, this group has people who might be able to help!
*** [[eprints-tech Mailing List|Click here]] for information about [[eprints-tech Mailing List#Subscription_Options|subscribing to this list]] or [[eprints-tech Mailing List#List_Archives|reading its archives]].
** '''[https://groups.google.com/forum/#!forum/eprints-uk-user-group The EPrints User Group Google Group]'''
*** This group is for anyone involved in using EPrints. Ask questions, share ideas, hear about forthcoming meetings.
* How to [[Main_Page#Contributing_to_the_Wiki|contribute to the EPrints wiki]]
* EPrints source code on GitHub:
** Core and major plugins - https://github.com/eprints
** Community code sharing - https://eprintsug.github.io and the repositories at https://github.com/eprintsug

== Download EPrints ==

{{Download}}

==Installation==

* [[:Category:Installation|Installing]] EPrints on various platforms

==Getting Started==

* [[EPrints Manual|EPrints 3 Documentation]]
* [[Perl 101 for EPrints]]
* [https://www.eprints.org/software/training/ Training materials] provided by EPrints Services.
* [[Frequently Asked Questions]]
* [[:Category:Howto|How to ...]]
* [[:Category:Plugins|Plugins and Bazaar packages for EPrints]]
* [[:Category:Training Video|EPrints Training Course]]

==Getting Support==

* [https://www.eprints.org/services/ EPrints Services] - premium support, training and hosting from EPrints experts
* [[Contact]] - mailing lists, bug reports etc.
* [[User group meetings]] - regional meetings for users, which often have notes, presentations and information of general interest

==Add-ons, patches and translations==

* As of version 3.3 EPrints can now install plugins and translations through the [https://bazaar.eprints.org EPrints Bazaar] the wiki also has information about [[:Category:EPrints Bazaar|packaging plugins for the Bazaar]].
* The [https://files.eprints.org/ EPrints Files Repository] contains add-on and 3rd party scripts, patches and translations. This also provides an archive of all previous EPrints releases (3.0 onwards).
* [[:Category:Plugins|Plugins]]: Some Wiki pages about scripts and patches.

{{Register}}

==Contributing to EPrints==

* [[Usability|EPrints usability]]
* New features in EPrints - [[:Category:Releases|released]] and [[:Category:Planned Releases|proposed]]
* [[How to contribute|How to contribute to EPrints development]]
* [https://github.com/eprints/eprints3.4 EPrints 3.4 on GitHub] - Codebase, releases and issues tracker for EPrints 3.4.
* [https://github.com/eprints/eprints3 EPrints 3.3 on GitHub] - Codebase, releases and issues tracker for EPrints 3.3 (legacy).

== Content management ==

* [[Digital preservation]]: managing content for longer-term access and use

Template:EPrintsTech

2024-02-16T17:32:14Z

Th.lauke@arcor.de: link updated

For free support and discussion about EPrints you can sign up to [[Eprints-tech_Mailing_List | EP-Tech]].

Template:Download

2024-02-16T17:22:18Z

Th.lauke@arcor.de: download link updated

* '''EPrints 3.4 series (latest release)'''
** [[Upgrading_3.3.12%2B_to_3.4|'''Read this before upgrading your archive from 3.3 to 3.4''']]
** [[Upgrading between EPrints 3.4 versions]]
** [http://files.eprints.org/2789/ Download]
** [https://github.com/eprints/eprints3.4 Development]
* '''EPrints 3.3 series (legacy supported release)'''
** [[Upgrading_from_3.2|'''Read this before upgrading your archive from 3.2 to 3.3''']]
** [https://files.eprints.org/2306/ Download]
** [https://files.eprints.org/2349/ February 2021 security patch for EPrints 3.3.16]
** [https://github.com/eprints/eprints Legacy development]

Debian from source

2024-02-16T17:03:24Z

Th.lauke@arcor.de: outdated strategy removed

#REDIRECT [[Installing_EPrints_on_Debian/Ubuntu#Installing_EPrints_from_Source | Installing EPrints from Source]]

Admin

2024-02-16T16:08:34Z

Th.lauke@arcor.de: typo removed, category added

[[Category:Management]]
<div style="border: solid black 1px; text-align: center; background-color: #eee; padding-bottom: 0.5em">
'''Admin:''' {{admin_tabs}}
</div>

The page pertains to the '''Admin''' web interface of an EPrints repository, which provides tools for an administrator to manage their repository. As a logged in repository administrator, it can be accessed by clicking on the ''Admin'' link in the EPrints [[User Menu]] or at the following equivalent URL on your repository:
https://example.eprints.org/cgi/users/home?screen=Admin

By default this will display three tabs of administration sub-menus:
# [[Admin/Editorial Tools|Editorial Tools]] - Tools to support editorial tasks. Typically searching across various different datasets.
# [[Admin/System Tools|System Tools]] - Tools for controlling the EPrints System. Checking the status, controlling the indexer, interacting with the Bazaar, regenerating pages, etc.
# [[Admin/Config. Tools|Config. Tools]] - Tools for modifying the EPrints repository configuration. Editing subjects, phrases of configuration files directly, updating the database, reloading configuration and managing storage.

EPrints and MariaDB 10

2024-02-08T08:47:03Z

Th.lauke@arcor.de: typo removed

Various changes have been made to MariaDB between version 5.5 and 10 and these can have some impact on EPrints.

== Not Null without Default Value ==
In EPrints a MetaField can set the attribute <tt>allow_null => 0</tt>. This means strictly it has has to have a default value. Prior to EPrints 3.4.4, default values were not set for MetaFields created with <tt>allow_null => 0</tt> and not [https://github.com/eprints/eprints3.4/issues/196 until EPrints 3.4.5] were the default values tailored depending on the type of database field. [[EPrints_and_MySQL_8 | MySQL 8]] also has the same issue.

If you are running an earlier version of EPrints, you could manually alter your database to make sure any MetaField that have <tt>allow_null => 0</tt> and set a default value something like:
ALTER TABLE `eprint` MODIFY COLUMN `not_null_field` VARCHAR(255) NOT NULL DEFAULT '';
Otherwise, you could change your MySQL server's configuration to overlook this by adding the following to <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> (and affectively removing the part of <tt>STRICT_TRANS_TABLES</tt> that causes this to error). Once done remember to restart MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

== Data Too Long for Field ==
EPrints often uses <tt>VARCHAR(255)</tt> fields. This can sometime present a problem especially if the text contains special characters which in affect makes the column even less than 255 characters. Previously MySQL has just truncated data that has got to long but in MariaDB 10 (as well as [[EPrints_and_MySQL_8 | MySQL 8]]) it now just throws an error message.

The main place in EPrints this is a problem is indexing metadata and the full text of documents. Since [https://github.com/eprints/eprints3.4/issues/247 EPrints 3.4.5], a restriction on the max length of a word that can be indexed has been added to restrict this to 128 characters, this ensures that even if special characters are used the total space required to store the string does not exceed that available to a <tt>VARCHAR(255)</tt> by some margin.

However, if you are running an earlier version of EPrints, the only solution for now is the same as for the "[[#Not Null without Default Value|Not Null without Default Value]]" issue and setting the SQL mode in <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> as follows and then restarting MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
Like this other issue it is <tt>STRICT_TRANS_TABLES</tt> that will throw an error rather than quietly truncate, which although also not ideal is generally less problematic as terms that are too long are unlikely ever to be those searched.

[[Category:Installation]]

EPrints and MariaDB 10

2024-02-08T08:39:30Z

Th.lauke@arcor.de: typos removed

Various changes have been made to MariaDB between version 5.5 and 10 and these can have some impact on EPrints.

== Not Null without Default Value ==
In EPrints a MetaField can set the attribute <tt>allow_null => 0</tt>. This means strictly it has has to have a default value. Prior to EPrints 3.4.4, default values were not set for MetaFields created with <tt>allow_null => 0</tt> and not [https://github.com/eprints/eprints3.4/issues/196 until EPrints 3.4.5] were the default values tailored depending on the type of database field. [[EPrints_and_MySQL_8 | MySQL 8]] also has the same issue.

If you are running an earlier version of EPrints, you could manually alter your database to make sure any MetaField that have <tt>allow_null => 0</tt> and set a default value something like:
ALTER TABLE `eprint` MODIFY COLUMN `not_null_field` VARCHAR(255) NOT NULL DEFAULT '';
Otherwise, you could change your MySQL server's configuration to overlook this by adding the following to <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> (and affectively removing the part of <tt>STRICT_TRANS_TABLES</tt> that causes this to error). Once done remember to restart MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

== Data Too Long for Field ==
EPrints often uses <tt>VARCHAR(255)</tt> fields. This can sometime present a problem especially if the text contains special characters which in affect makes the column even less than 255 characters. Previously MySQL has just truncated data that has got to long but in MariaDB 10 (as well as MySQL 8) it now just throws and error message.

The main place in EPrints this is a problem is indexing metadata and the full text of documents. Since [https://github.com/eprints/eprints3.4/issues/247 EPrints 3.4.5], a restriction on the max length of a word that can be indexed has been added to restrict this to 128 characters, this ensures that even if special characters are used the total space required to store the string does not exceed that available to a <tt>VARCHAR(255)</tt> by some margin.

However, if you are running an earlier version of EPrints, the only solution for now is the same as for the "[[#Not Null without Default Value|Not Null without Default Value]]" issue and setting the SQL mode in <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> as follows and then restarting MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
Like this other issue it is <tt>STRICT_TRANS_TABLES</tt> that will throw an error rather than quietly truncate, which although also not ideal is generally less problematic. As terms that are too longer are unlikely ever to be those searched.

[[Category:Installation]]

EPrints and MySQL 8

2023-12-28T14:40:22Z

Th.lauke@arcor.de: typos removed

Various changes have been made to MySQL between version 5.7 and 8 and these can have some impact on EPrints.

== Slow Performance ==
By default EPrints now uses InnoDB as its table engine. As EPrints can make a lot of transactions to update a eprint record whilst in the workflow, as well as complex background tasks this means the default configuration of MySQL makes EPrints rather slower than before. This can be fixed by adding the following line to <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt>:
innodb_flush_log_at_trx_commit=2
What this change does is ensure the logs are flushed once a second rather than after each transaction commit. This is not ideal as your bin logs could potential miss transactions if the database was to crash but does significantly improve the performance of EPrints. Further investigation is required to determine how serious an impact lost transactions from the bin logs would be for EPrints. At worse this would likely affect only a small number of eprints.

== Not Null without Default Value ==
In EPrints a MetaField can set the attribute <tt>allow_null => 0</tt>. This means strictly it has to have a default value. Prior to EPrints 3.4.4, default values were not set for MetaField's created with <tt>allow_null => 0</tt> and not [https://github.com/eprints/eprints3.4/issues/196 until EPrints 3.4.5] were the default values tailored depending on the type of database field. MariaDB 10 also has the same issue.

If you are running an earlier version of EPrints, you could manually alter your database to ensure that any MetaFields that have <tt>allow_null => 0</tt> and set a default value something like:
ALTER TABLE `eprint` MODIFY COLUMN `not_null_field` VARCHAR(255) NOT NULL DEFAULT '';
Otherwise, you could change your MySQL server's configuration to overlook this by adding the following to <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> (and affectively removing the part of <tt>STRICT_TRANS_TABLES</tt> that causes this to error). Once done remember to restart MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION

== Data Too Long for Field ==
EPrints often uses <tt>VARCHAR(255)</tt> fields. This can sometime present a problem especially if the text contains special characters which in affect makes the column even less than 255 characters. Previously MySQL has just truncated data that has got to long but in MySQL 8 (as well as MariaDB 10) it now just throws and error message.

The main place in EPrints this is a problem is indexing metadata and the full text of documents. Since [https://github.com/eprints/eprints3.4/issues/247 EPrints 3.4.5], a restriction on the max length of a word that can be indexed has been added to restrict this to 128 characters, this ensures that even if special characters are used the total space required to store the string does not exceed that available to a <tt>VARCHAR(255)</tt> by some margin.

However, if you are running an earlier version of EPrints, the only solution for now is the same as for the "[[#Not Null without Default Value|Not Null without Default Value]]" issue and setting the SQL mode in <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> as follows and then restarting MySQL:
sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
Like this other issue it is <tt>STRICT_TRANS_TABLES</tt> that will throw an error rather than quietly truncate, which although also not ideal is generally less problematic. As terms that are too longer are unlikely ever to be those searched.

== Deprecation Warnings ==
Some of the more recent versions of MySQL state that some of the options in <tt>sql_mode</tt> have been deprecated. In particular: <tt>NO_ZERO_IN_DATE</tt>, <tt>NO_ZERO_DATE</tt> and <tt>ERROR_FOR_DIVISION_BY_ZERO</tt>. Therefore, you should additional remove these to leave SQL mode in <tt>/etc/mysql/mysql.conf.d/mysqld.cnf</tt> looking like:
sql_mode=ONLY_FULL_GROUP_BY,NO_ENGINE_SUBSTITUTION

[[Category:Installation]]

EPrints Flavours

2023-02-21T18:30:06Z

Th.lauke@arcor.de: typos removed, links added

Since EPrints 3.4 flavours have been introduced into EPrints. Flavours provide customisation for different types of EPrints. The following three flavours are currently available:
# '''Publications''' - This is the original EPrints for research publications. Its flavours sub-directory is '''[[flavours/pub_lib/|pub_lib]]''', which comes as part of the core codebase but is provided separately on [https://files.eprints.org files.eprints.org].
# '''Research Data''' - This provides specific customisations for research data. Its flavours sub-directory is '''[[flavours/data_lib/|data_lib]]'''.
# '''Open Education''' - This provides specific customisations for open education, previously known as EdShare. Its flavours sub-directory is '''[[flavours/edu_lib/|edu_lib]]'''.

== Installing a Flavour ==
If you install EPrints from [https://files.eprints.org files.eprints.org] instead of before when you could just download a single tarball, you will need to:

# Download the '''EPrints Zero''' tarball which is a base version of EPrints without any specializations for publications, like was the case for EPrints 3.3 and earlier.
# Unpack the '''EPrints Zero''' tarball to '''[[EPrints_Directory_Structure_Tree|/opt/eprints3/]]'''
# Download the flavour you want, such as the publication flavour tarball, and unpack it into '''[[EPrints_Directory_Structure/eprints3/flavours|/opt/eprints3/flavours/]]'''.

After you have finished installing EPrints as a flavour, you may also want to add [[EPrints Ingredients|Ingredients]]. Ingredients are often similar to [https://bazaar.eprints.org Bazaar] plug-ins and intend to replace some of the more complex Bazaar plug-ins, which are not really suited to a one-click installation as they need extensive configuration and/or non-EPrints dependencies.

[[Category:Customisation]]

Flavours/

2023-02-21T18:05:51Z

Th.lauke@arcor.de: data_lib & edu_lib added

{{dirs}}
{{noeditdir}}

The '''flavours/''' directory contains the libraries for the [[EPrints Flavours|flavour]] or flavours for repository archives. This directory (and below) should not be edited by hand only to add additional complete flavour libraries.

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/flavours'''
** '''[[Flavours/pub_lib/|pub_lib/]]''' - Publication flavour library.
** '''[[Flavours/data_lib/|data_lib/]]''' - Research Data flavour library.
** '''[[Flavours/edu_lib/|edu_lib/]]''' - Open Education flavour library.

Configuration orientation

2023-02-21T18:05:16Z

Th.lauke@arcor.de: sitewide configuration added

[[Category:Howto]]
[[Category:Manual]]
[[Category:Configuration]]

You've just installed EPrints 3 and created a repository, and now you're keen to get started on customising it. Before diving into the how-tos, take some time to read through this brief orientation guide and familiarise yourself with the EPrints configuration landscape.

__TOC__

==Where are the configuration files?==

The default installation directory for EPrints is:

/opt/eprints3/

(You may have chosen a different installation directory when you installed EPrints.)

There are several sub-directories at this level, but this guide covers only those relevant to repository configuration - the ''lib'' and ''archives'' directories. Before looking at the contents of these directories, we need to understand the concepts of ''global'' and ''repository-specific'' (or ''local'') configuration. If several repositories running on your server are very similar you should consider a [[sitewide configuration]].

'''What about everything else?''' The EPrints installation directory contains several other files and directories, which are described in the [[EPrints Directory Structure]] section.

==Local vs global configuration==

A single installation of EPrints can run multiple repositories, each potentially very different in style and functionality. Therefore, EPrints configuration files are divided into two default sets: ''global configuration'' and ''repository-specific configuration''. Each repository shares the global configuration settings, whilst keeping its own set of local (private) configuration settings.

EPrints tries to strike a sensible balance between the two sets. The global set contains the configuration options that you are probably least likely to need to change (although they are by no means unchangeable - you can override a global setting for a specific repository if you need to). On the other hand, the repository-specific set contains the most often tweaked settings.

===The ''lib'' directory===

[[Image:Orientation_lib.png|right]]

The lib directory is where the global configuration files are kept. '''This directory should be considered [[Read Only Directories|read only]]'''. Best practice when changing a global setting for a particular repository is to override the setting at the repository level rather than edit the global configuration files directly. The configuration files in ''lib'' are organised into subdirectories according to their function, which should help make locating a specific configuration setting intuitive.

[[EPrints_Directory_Structure/eprints3/lib|Explore the contents of the lib directory]].

Note that the ''defaultcfg'' subdirectory contains the default set of configuration files that are copied into each new repository's local configuration directory. These local configuration directories are covered in the next section.

<br clear="all" />

===The ''archives'' directory===

[[Image:Orientation_cfg.png|right]]

Each repository has its own subdirectory (named according to the repository id) under the ''archives'' directory.

Each repository directory contains several [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID|subdirectories]], including the ''cfg'' directory. This is where the repository-specific configuration files are kept.

[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|Explore the contents of the cfg directory]].

EPrints Directory Structure Tree

2023-02-21T18:02:19Z

Th.lauke@arcor.de: site_lib added

{{dirs}}

A graphical representation of the [[EPrints Directory Structure|EPrints3 directory structure]] after executing the install.pl command. Initially the "archives" directory is empty, it is populated when executing (as the eprints user) the "bin/epadmin create" command. The new repository is created using the data in the [[EPrints_Directory_Structure/eprints3/lib/defaultcfg]] directory.

<div style="margin:2em; background-color:#e9e9e9;">
<table cellpadding="0" cellspacing="2" style="margin: 6px; background-color:#e9e9e9;">
<tr><td>[[EPrints_Directory_Structure/eprints3/perl_lib|perl_lib]]</td>
<td>[[Image:jobbra.png|->]]</td>
<td colspan="10">[<i>perl routines</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/bin|bin]]</td>
<td>[[Image:jobbra.png|->]]</td>
<td colspan="10">[<i>command line and crontab tools</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/cgi|cgi]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>dynamic (cgi) EPrints web pages</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/cfg|cfg]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>apache configuration for the whole site</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/testdata|testdata]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>tools and sample test data</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/tests|tests]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>unit tests</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/tools|tools]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>command line tools</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/var|var]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>apache include files plus indexer log</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/site_lib|site_lib]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="10">[<i>for customized system [[EPrints_Directory_Structure/eprints3/lib|lib]] files or [[sitewide configuration]] concurrent to [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|archives/[ArchiveID]/cfg]]</i>]</td></tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/lib|lib]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/cfg.d/|cfg.d]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>core config files</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/citations/|citations]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="4">[<i>how to render data objects</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/defaultcfg_zero/|defaultcfg_zero]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>the content of</i> archives/ID/cfg/ <i>is copied from here</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/lang/|lang]]</td>
<td>[[Image:jobbra.png]]</td>
<td>XX (langid)</td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/lang/en/phrases/|phrases]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>system-wide phrases</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/lang/en/static/|static]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>web pages and icons</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/namedsets/|namedsets]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>options for namedset fields</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>plugins</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>extra EPrints plugins</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/static/|static]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>files to be copied to the html directory</i>]</td>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/syscfg.d/|syscfg.d]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>system config files</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/templates/|templates]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>web page templates</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png|"->"]]</td>
<td>[[Lib/themes/|themes]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/|example]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/lang/|lang]]</td>
<td>[[Image:jobbra.png]]</td>
<td>XX (langid)</td>
<td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/lang/en/phrases/|phrases]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>theme phrases</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/lang/en/static/|static]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>theme language-specific pages</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/lang/en/templates/|templates]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>theme language-specific templates</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/static/|static]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>theme CSS and images</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/themes/example/templates/|templates]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>theme templates</i>]</td>
</tr>
<tr><td></td><td>[[Image:jobbra.png]]</td>
<td>[[Lib/workflows/|workflows]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="4">[<i>workflows for data objects</i>]</td>
</tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/flavours|flavours]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[[Flavours/pub_lib/|pub_lib]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>see [[EPrints Flavours|3.4+ publication flavour]]</i>]</td>
</tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/ingredients|ingredients]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>see [[EPrints Ingredients|3.4+ ingredients]]</i>]</td>
</tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/archives|archives]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID|ARCHIVEID]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>see below</i>]</td>
</tr>
</table>
</div>

The content of the "archives/[ArchiveID]/" directory. Any change you make here has effect on the particular repository only.

<div style="margin:2em; background-color:#e9e9e9;">
<table cellpadding="0" cellspacing="2" style="margin: 6px; background-color:#e9e9e9;">
<tr><td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/documents|documents]] </td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>uploaded files, extracted words, abstract pages, etc.</i>]</td>
</tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/html|html]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>static files for the repository on all languages</i>]</td>
</tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/var|var]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">[<i>various repository dependent files</i>]</td>
</tr>
<tr><td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|cfg]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="7">subjects [<i>used for importing the subject tree</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static|static]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static/images|images]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="3">[<i>files to be copied to the html directory</i>]</td>
</tr>
<tr><td></td><td></td><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static/javascript|javascript]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="3">[<i>files to be copied to the html directory</i>]</td>
</tr>
<tr><td></td><td></td><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/static/style|style]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="3">[<i>files to be copied to the html directory</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/cfg.d|cfg.d]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="5">[<i>general configuration files as perl script fragments</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/autocomplete|autocomplete]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="5">[<i>data files for the autocompletion feature</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/citations|citations]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>directories for citations for different data objects</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/namedsets|namedsets]]</td>
<td>[[Image:jobbra.png]]</td>
<td colspan="5">[<i>files containing the possible values for different sets</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/workflows|workflows]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>directories for workflows for different data objects</i>]</td>
</tr>
<tr><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang|lang]]</td>
<td>[[Image:jobbra.png]]</td>
<td>XX (langid)</td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases|phrases]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>phrases used locally</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static|static]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>templates for static html pages</i>]</td>
</tr>
<tr><td></td><td></td><td></td><td></td><td></td>
<td>[[Image:jobbra.png]]</td>
<td>[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/templates|templates]]</td>
<td>[[Image:jobbra.png]]</td>
<td>[<i>default html page template</i>]</td>
</tr>
</table>
</div>

EPrints Directory Structure/eprints3/site lib

2023-02-21T18:01:08Z

Th.lauke@arcor.de: initial creation of new content

[[Category:EPrints_Directory_Structure]]
{{dirs}}

The '''site_lib/''' directory may contain the customized version of the data directories files originally located for the EPrints system in [[EPrints_Directory_Structure/eprints3/lib|eprints3/lib]] (except [[Lib/defaultcfg_zero/|defaultcfg_zero]]).
Assuming you are running several similar sites by one server this directory facilitates the maintenance of the overall configuration!
The appropriate order in [[flavours/pub_lib/inc|eprints3/flavours/pub_lib/inc]] controls which configuration file is used in favour of all files not found in the subdirectories below [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|eprints3/archives/[ArchiveID]/cfg]].

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/site_lib'''
** '''[[Lib/cfg.d/|cfg.d/]]''' - Perl configuration files.
** '''[[Lib/citations/|citations/]]''' - Citation configuration files which are not repository specific.
** '''[[Lib/lang/|lang/]]''' - Language specific lib data files.
** '''[[Lib/namedsets/|namedsets/]]''' - Options for [[API:EPrints/MetaField/Namedset|namedset]] fields.
** '''plugins/''' - Empty directory but all customized plugins could be added here.
** '''[[Lib/static/|static/]]''' - Language neutral items which appear in the website of every eprints repository (eg. javascript and arrow icons).
** '''[[Lib/syscfg.d/|syscfg.d/]]''' - System Perl configuration files.
** '''[[Lib/templates/|templates/]]''' - Web page templates.
** '''[[Lib/themes/|themes/]]''' - Themes that can be used by a repository.
** '''[[Lib/workflows/|workflows/]]''' - Workflow configuration files which are not repository specific.

Sitewide configuration

2023-02-21T17:58:49Z

Th.lauke@arcor.de: initial creation of new content

[[Category:Customisation]]

Assuming you are running several similar sites by one server using [[EPrints_Directory_Structure/eprints3/site_lib|eprints3/site_lib]] facilitates the maintenance of the overall configuration!
The appropriate order in e.g. [[flavours/pub_lib/inc|eprints3/flavours/pub_lib/inc]] controls which configuration file is used in favour of all files not found in the subdirectories below [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|archives/[ArchiveID]/cfg]]. Thus you can define your personally customized version which will be pushed somewhere in between the probably existing ones in [[EPrints_Directory_Structure/eprints3/lib|eprints3/lib]], [[EPrints_Directory_Structure/eprints3/flavours|eprints3/flavours/[pub|data|edu]_lib]] or [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg|archives/[ArchiveID]/cfg]].