EPrints Documentation - Recent changes [en-gb]

Setting up email

Ap1e26 — Fri, 16 Oct 2026 12:11:31 GMT

← Older revision		Revision as of 12:11, 16 October 2026
(One intermediate revision by the same user not shown)
Line 1:		Line 1:
	{{Manual}}		{{Manual}}
	There are two different ways of configuring EPrints to send email. You can either edit EPrints configuration to set the SMTP server or your can use Postfix or similar applications and set them up as a smarthost that can relay email via another SMTP server.		There are two different ways of configuring EPrints to send email. You can either edit EPrints configuration to set the SMTP server (handy for testing) or your can use Postfix or similar applications and set them up as a smarthost that can relay email via another SMTP server (our recommended solution).

			== Configuring Postfix as an Email Smarthost ==
			Follow instructions on how to install Postfix and configure as a smarthost at https://www.cyberciti.biz/faq/how-to-configure-postfix-relayhost-smarthost-to-send-email-using-an-external-smptd/ There is no need to reload the webserver once you have finished, as nothing should have changed in the EPrints configuration.

			The advantage of installing Postfix as a smarthost is that you can check /var/log/maillog if there are problems with email being sent, which should make it easier to determine whether it is the EPrints server or the SMTP server that is causing the problem.

	== Configuring SMTP in EPrints ==		== Configuring SMTP in EPrints ==
Line 15:		Line 20:
	The advantage of using this method is that it will not effect how mail is sent by any other applications on the server. The disadvantage is it may be difficult to debug if users do not receive email as expected.		The advantage of using this method is that it will not effect how mail is sent by any other applications on the server. The disadvantage is it may be difficult to debug if users do not receive email as expected.

	~~== Configuring Postfix as an Email Smarthost ==~~
	Follow instructions on how to install Postfix and configure as a smarthost at https://www.cyberciti.biz/faq/how-to-configure-postfix-relayhost-smarthost-to-send-email-using-an-external-smptd/ There is no need to reload the webserver once you have finished, as nothing should have changed in the EPrints configuration.

	The advantage of installing Postfix as a smarthost is that you can check /var/log/maillog if there are problems with email being sent, which should make it easier to determine whether it is the EPrints server or the SMTP server that is causing the problem.

	[[Category:Configuration]]		[[Category:Configuration]]

Branding/Logos

Ap1e26 — Fri, 16 Oct 2026 12:08:24 GMT

Ap1e26 moved page Branding/Logos to Archive:Branding/Logos This targets an old version, more in depth guide available

New page

{{Template:Deprecated}}
{{manual}}
[[Category:Branding]]
There are several different types of page in the eprints WebsiteInterface and they are generated in different ways. See WebsiteInterface for an explanation.

Every page on eprints is wrapped in the site template. This can be found at /opt/eprints2/archives/myid/cfg/template-en.xml

==Changing the Template==

Edit /opt/eprints2/archives/myid/cfg/template-en.xml

Make your changes. Be careful not to remove the <pin> elements as this is how eprints knows where to insert information.

Note that this file is XML so all tags must be closed correctly.

==Cause the new template to be applied==

TIP: If you want to see the new template in situ without waiting to update all the webpages then run "generate_abstracts myid 66" (or some other existing abstract page) and see the change on that one page.

This is slightly different for each part of the site...

=== [[EPrints_Glossary#Static page | Static pages]] ===
run generate_static

=== [[EPrints_Glossary#Abstract page | Abstract pages]]===

run generate_abstracts

=== [[EPrints_Glossary#EPrint view page | View pages]] ===

run generate_views

=== [[EPrints_Glossary#Dynamic Pages | Dynamic pages]] ===

run force_config_reload or resart the webserver

Branding with confidence

Ap1e26 — Fri, 16 Oct 2026 12:07:43 GMT

← Older revision		Revision as of 12:07, 16 October 2026
Line 1:		Line 1:
	[[Category:Branding]]		[[Category:Branding]]
			{{manual}}
	One of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface - this may include logos, page layouts, stylesheets and colour schemes.		One of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface - this may include logos, page layouts, stylesheets and colour schemes.

Template:Manual

Ap1e26 — Fri, 16 Oct 2026 12:07:13 GMT

← Older revision		Revision as of 12:07, 16 October 2026
Line 17:		Line 17:
	*** [[Setting up email]]		*** [[Setting up email]]
	* Configuring EPrints		* Configuring EPrints
	** [[Branding~~/Logos~~]]		** [[Branding with confidence]]
	** [[Metadata\|Deposit Types and Metadata]]		** [[Metadata\|Deposit Types and Metadata]]
	** [[Organisation Hierarchy]]		** [[Organisation Hierarchy]]

Branding/Logos

Ap1e26 — Fri, 16 Oct 2026 12:06:19 GMT

← Older revision		Revision as of 12:06, 16 October 2026
Line 1:		Line 1:
			{{Template:Deprecated}}
	{{manual}}		{{manual}}
	[[Category:Branding]]		[[Category:Branding]]

How to use EPrints with HTTPS

Ap1e26 — Fri, 16 Oct 2026 10:34:45 GMT

← Older revision		Revision as of 10:34, 16 October 2026
(2 intermediate revisions by the same user not shown)
Line 3:		Line 3:
	[[Category:Authentication]]		[[Category:Authentication]]

	'''This guide is intended for EPrints 3.3 or later,~~<br/>~~ but the [[Simplified_HTTPS_Configuration \| Update]] may be more appropriate for this current version!'''		'''This guide is intended for EPrints 3.3 or later and is a good staring point, but the [[Simplified_HTTPS_Configuration \| Update]] may be more appropriate for this current version!'''

	'''N.B.''' Setting up your Apache Web server is beyond the scope of this document. Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.'''		'''N.B.''' Setting up your Apache Web server is beyond the scope of this document. Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.'''

			== Before you Begin ==
			This guide assumes you have already got your SSL certificates or know how to get them when required. We mostly do this using Let's Encrypt, and have a [[Setting up HTTPS using Let's Encrypt \| handy guide]] on it.

	== Configuration ==		== Configuration ==

Troubleshooting

Ap1e26 — Fri, 16 Oct 2026 09:55:30 GMT

A Note on SELinux

← Older revision		Revision as of 09:55, 16 October 2026
(One intermediate revision by the same user not shown)
Line 11:		Line 11:
	===(Under SuSE Linux) Apache has problems compiling the mod rewrite module===		===(Under SuSE Linux) Apache has problems compiling the mod rewrite module===
	With an error something like:		With an error something like:


	~~<code>~~
	In file included from mod_rewrite.c:93:		In file included from mod_rewrite.c:93:
	mod_rewrite.h:133: ndbm.h: No such file or directory		mod_rewrite.h:133: ndbm.h: No such file or directory
	~~</code>~~
	Possible cause: Missing the ndbm library which is required (for some reason).		Possible cause: Missing the ndbm library which is required (for some reason).

Line 67:		Line 64:
	If you run your EPrints Apache server as user eprints this isn't an issue, however if you run Apache as apache you will need to run:		If you run your EPrints Apache server as user eprints this isn't an issue, however if you run Apache as apache you will need to run:

	chcon -R -t httpd_sys_content_t /opt/eprints2/		chcon -R -t httpd_sys_content_t /opt/eprints2/

	To allow the apache process to access the eprints files (in addition to any Unix permission changes necessary).		To allow the apache process to access the eprints files (in addition to any Unix permission changes necessary).

HTTPS2

Ap1e26 — Wed, 14 Oct 2026 10:13:09 GMT

Ap1e26 moved page HTTPS2 to Archive:HTTPS2 This is very old

New page

[[Category:Authentication]]
==Add HTTPS Settings==

For each <tt>ARCHIVEID.xml</tt> file, fill in the <tt>securehost</tt> and <tt>securepath</tt> entries.

Example:

<archive id="demo">
....
<securehost>secure.mydomain.com</securehost>
<securepath>/demo</securepath>
....
</archive>

The <tt>securehost</tt> is vhosted on the same server as your EPrints archive(s).

Secure requests will be of the form <tt>https://securehost/securepath</tt>.

<tt>securepath</tt> therefore differentiates requests from individual archives.

==Generate Secure Config==

$ bin/generate_apacheconf

As well as the usual apache configuration files, and depending on the version of EPrints, this will generate:

* an <tt>auto-secure.conf</tt> file in each archive's <tt>cfg</tt> directory (2.3.13)
* an <tt>auto-your.secure.host.conf</tt> file (for each secure host) in the main <tt>cfg</tt> directory (2.3.11)

==Set up Secure Host==

Under Fedora Core 4, run:

$ yum install mod_ssl

This sets up a test SSL server.

===Certificates===

For a production system, you would need to provide the relevant certificates and tweak the mod_ssl config accordingly - see:

* [http://httpd.apache.org/docs/2.2/mod/mod_ssl.html Apache Module mod_ssl]
* [http://www.modssl.org/docs/2.8/ssl_faq.html mod_ssl FAQ]

Create a <tt>server.key</tt> on the EPrints server (remembering the passphrase you enter):

$ openssl genrsa -des3 -out server.key 1024

Create a certificate request:

$ openssl req -new -key server.key -out server.csr

The important thing when answering the questions is the CommonName: if ultimately the secure web address of your EPrints server is <tt>https://www.myeprints.com</tt>, then the CommonName value to enter is exactly <tt>www.myeprints.com</tt>.

Send the <tt>server.csr</tt> file to your Certificate Authority administrator, who should send you back a <tt>.cer</tt> file.

Copy <tt>server.key</tt> and the <tt>.cer</tt> file to the following locations:

/etc/httpd/conf/ssl.key/server.key
/etc/httpd/conf/ssl.crt/eprints.cer

Modify <tt>/etc/httpd/conf.d/ssl.conf</tt> accordingly:

SSLCertificateFile /etc/httpd/conf/ssl.crt/eprints.cer
SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key

===Include EPrints SSL config===

Include each <tt>auto-secure.conf</tt> file generated by EPrints inside the <tt>Virtualhost</tt> directive.

On FC4, edit <tt>/etc/httpd/conf.d/ssl.conf</tt>:

<VirtualHost _default_:443>
....
Include /opt/eprints2/archives/ARCHIVEID/cfg/auto-secure.conf # 2.3.13
Include /opt/eprints2/cfg/auto-your.secure.host.conf # 2.3.11
Include /opt/eprints3/archives/soton/var/auto-secure.conf # 3.0.0
</VirtualHost>

If you have set up SSL certificates, you will be asked to enter your passphrase when you restart apache. To override this, see [http://www.modssl.org/docs/2.8/ssl_faq.html#remove-passphrase How can I get rid of the pass-phrase dialog at Apache startup time?].

==Create Template for Secure Pages==

Make a copy of the default template in <tt>archives/ARCHIVEID/cfg/lang/en/templates/</tt>:

$ cp default.xml secure.xml

In a multi-language archive, you would need to do this for each language-specific template (en = ENglish).

It's a good idea to have a visual differentiation between secure and non-secure pages, e.g. edit <tt>secure.xml</tt> and add "(SECURE)" to the title of the page.

Some browsers will complain if images/CSS etc. embedded in a secure page are served by the non-secure host. To solve this modify the <tt>secure_urlpath</tt> and <tt>secure_url</tt> entries in <tt>archives/ARCHIVEID/cfg/cfg.d/20_baseurls.pl</tt>:

$c->{secure_urlpath} = "";
$c->{secure_url} = "https://".$c->{securehost}.$c->{securepath};

In the <tt>secure.xml</tt> template replace image/CSS <tt>base_url</tt>s with <tt>secure_url</tt>.

BUG FIX: In bin/generate_static replace <tt>import url($base_url$1);</tt> with <tt>import url($1);</tt>.

At the top of the page, replace the reference to '''/javascript/auto.js''' with '''/javascript/secure_auto.js'''.

At the top of auto.js, there are the following 3 lines:
var eprints_http_root = "http:\/\/myrepository.ac.uk";
var eprints_http_cgiroot = "http:\/\/myrepository.ac.uk\/cgi";
var eprints_oai_archive_id = "myrepository.ac.uk";
... in secure_auto.js, these must start with 'https' rather than just 'http'.

Https3

Ap1e26 — Wed, 14 Oct 2026 10:12:22 GMT

Ap1e26 moved page Https3 to Archive:Https3 This is very old

New page

[[Category:Authentication]]
== Introduction ==

'''EPrints 3.0.5/3.1 introduces a new mechanism to set up HTTPS that greatly simplifies the process, see [[HTTPS]].'''

Setting up EPrints3 to work with https is a little tricky. There seems to be a few bugs to be worked round. This How To considers the following scenario:

* Two repositories, repos1 and repos2, being served by virtual hosts repos1.FQDN:80 and repos2.FQDN:80

* A single https domain, at eprints.FQDN:443 (so that only one certificate is needed). Secure pages for repos1 and repos2 will be accessed at eprints.FQDN:443/repos1 and eprints.FQDN:443/repos2 respectively.

This How To should work with EPrints 3.0 or 3.0.1. It was developed on Ubuntu Server 6.06, but should work on other systems without significant changes. The instructions can be adapted for an arbitrary number of repositories.

It is assumed that EPrints is installed in /opt/eprints3/.

== Getting started ==

Install EPrints 3.x following the appropriate instructions.

Run bin/epadmin create twice to create repos1 and repos2.

Edit /opt/eprints3/archives/repos1/cfg/cfg.d/10_core.pl to read:

$c->{host} = 'repos1.FQDN';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = 'eprints.FQDN';
$c->{securepath} = '/repos1';
$c->{secureport} = 443;

Make secure versions of the templates:

cp /opt/eprints3/archives/repos1/cfg/lang/en/templates/default.xml /opt/eprints3/archives/repos1/cfg/lang/en/templates/secure.xml

Repeat these steps for repos2.

Generate the Apache configuration:

/opt/eprints3/bin/generate_apacheconf

Add 'Include /opt/eprints3/cfg/apache.conf' to the Apache configuration (for Ubuntu / Debian, can replace everything in /etc/apache/sites-avaliable/default with 'Include /opt/eprints3/cfg/apache.conf'). Apache should now be correctly configured to serve the non-secure pages.

== Secure Apache Configuration ==

Next, we want to configure Apache to serve the secure pages. However, generate_apacheconf hasn't created a secure.conf file in /opt/eprints3/cfg/ so this needs to be done manually. Some configuration has been generated for us in /opt/eprints3/archives/repos1/var/auto-secure.conf and /opt/eprints3/archives/repos2/var/auto-secure.conf, but there are some problems with this:

* Some sections of the configuration overlap;
* The EPrints_ArchiveID and PerlSetVar EPrints_Secure variables have not been set.

We'll therefore create our own configuration. Create a new file called cfg/secure.conf:

#cfg/secure.conf:
NameVirtualHost *:443
<VirtualHost *:443>
ServerAdmin itsupport@FQDN
ServerName eprints.FQDN

SSLEngine On
SSLCertificateFile /etc/apache2/ssl/apache.pem

ErrorLog /var/log/apache2/error.log

# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn

CustomLog /var/log/apache2/access.log combined
ServerSignature On

DocumentRoot "/var/www/eprints"

<Directory "/opt/eprints3/cgi/users">
AuthName "User Area"
AuthType "Basic"
PerlAuthenHandler EPrints::Apache::Auth::authen
PerlAuthzHandler EPrints::Apache::Auth::authz
require valid-user

SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks
</Directory>
<Directory "/opt/eprints3/cgi/users/awstats">
PerlSendHeader On
</Directory>

<Directory "/opt/eprints3/cgi">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks
</Directory>

PerlTransHandler EPrints::Apache::Rewrite

Include /opt/eprints3/archives/repos1/var/manual-secure.conf
Include /opt/eprints3/archives/repos2/var/manual-secure.conf
</VirtualHost>

Not the line 'DocumentRoot "/var/www/eprints"'. Create an index.html file in /var/www/eprints/ with a welcome message and links to the home pages of the repositories. Also note that we need to create a manual-secure.conf file for each repository. The contents of this file are as follows:

#/opt/eprints3/archives/repos1s/var/manual-secure.conf

<Location "/repos1">
PerlSetVar EPrints_ArchiveID repos1
PerlSetVar EPrints_Secure yes
PerlSetVar EPrints_Dir_SecuredCGI /opt/eprints3/cgi/users
PerlSetVar EPrints_Dir_Documents /opt/eprints3/archives/repos1/documents
PerlLogHandler EPrints::Apache::LogHandler
</Location>

Alias /repos1/cgi/accounts/confirm /opt/eprints3/cgi/confirm
Alias /repos1/cgi/accounts/register /opt/eprints3/cgi/register
Alias /repos1/cgi/accounts/reset_password /opt/eprints3/cgi/reset_password
Alias /repos1/cgi/accounts/set_password /opt/eprints3/cgi/set_password
Alias /repos1/cgi/users/ /opt/eprints3/cgi/users/
Alias /repos1/ /opt/eprints3/archives/publications/html/

For completeness, we'll also want to add the welcome page to http: Add the following lines to /opt/eprints3/cfg/apache.conf

<VirtualHost *:80>
ServerName eprints.FQDN
ServerAdmin itsupport@FQDN
DocumentRoot "/var/www/eprints"
</VirtualHost>

Add 'Include /opt/eprints3/cfg/secure.conf' to the Apache configuration.

One thing remains. In /opt/eprints3/archives/repos1/cfg/cfg.d/misc.pl and /opt/eprints3/archives/repos2/cfg/cfg.d/misc.pl change the line

$c->{cookie_domain} = $c->{host};

to read

$c->{cookie_domain} = $c->{securehost};

Restart Apache. At this point it should be possible to access the repositories at http://publications.modhist.ox.ac.uk and http://oxhistonline.modhist.ox.ac.uk and log in to the secure area.

=== Debian / Ubuntu specific SSL instructions ===

Create a file called ssl in /etc/apache2/sites-available/ssl and add the line 'Include /opt/eprints3/cfg/secure.conf'. Run the commands:

a2ensite ssl
a2enmod ssl
apache2-ssl-certificate
echo "Listen 443" >> /etc/apache2/ports.conf

== Bugs ==

=== Broken Actions ===

Links which call Perl cgi scripts are broken – e.g. Under Manage Deposits, click New Item. Select an Item Type and then click Next. You will be returned to the Manage Deposits page, rather than to the next step in the workflow. This appears to be because the form action is pointing to http://publications.modhist.ox.ac.uk/cgi/users/home#t rather than /publications/cgi/users/home. As far as I can see, this is a bug, rather than a configuration mistake, though I'm happy to be advised otherwise.

The workaround I have for this bug is to install patch 252, which can be downloaded from http://files.eprints.org/252/

The patch seeks to resolve the problem by introducing a configuration variable users_url in 20_baseurls.pl. The use of perl_url has been replaced with users_url for all links to scripts in cgi/users. For insecure use, users_url can be set to perl_url. When https is requires, it can be adjusted appropriately.

Apply the patch to the EPrints 3.x source (patch -d eprints-3.0/ -p0 < users-url.patch) and re-run configure and install.pl. Add the following lines to /opt/eprints3/archives/repos1/cfg/cfg.d/20_baseurls.pl :

$c->{secure_urlpath} = $c->{securepath};
$c->{secure_url} = "https://".$c->{securehost}.($c->{secureport}!=443?":".$c->{secureport}:"").$c->{secure_urlpath};

# Mod_perl scripts for users scripts
# If not using https, make this the same as perl_url
# Otherwise make it $c->{secure_url}."/cgi"
#$c->{users_url} = $c->{perl_url};
$c->{users_url} = $c->{secure_url}."/cgi";

Similarly for /opt/eprints3/archives/repos2/cfg/cfg.d/20_baseurls.pl. Restart Apache. It should now be possible to upload documents, step through workflows etc.

However, some bugs with image urls remain.

=== Internet Explorer 'Secure and non Secure items' ===

We're not done yet! Internet Explorer complains if non-secure (http) and secure (https) items are displayed on the same page. This happens when a full url, beginning http:// is embedded in a page that is https. If the securepath and url_path variables were the same, e.g. we were using http://repos1.FQDN/repos1 and https://eprints.FQDN/repos1 then we could simply make all urls relative, but because they are different, e.g http://repos1.FQDN/ and https://eprints.FQDN/repos1 we must handle the secure and non-secure cases separately.

Edit /opt/eprints3/archives/repos1/cfg/lang/en/templates/secure.xml to use full https:// urls for included javascript and css and for the logo and .ico files. The head section should look something like this:

<head>
<title><epc:pin ref="title" textonly="yes"/> - <epc:phrase ref="archive_name"/></title>
<script src="{$config{secure_url}}/javascript/auto.js" type="text/javascript"></script>
<style type="text/css" media="screen">@import url(<epc:print expr="$config{secure_url}"/>/style/secure_auto.css);</style>
<style type="text/css" media="print">@import url(<epc:print expr="$config{secure_url}"/>/style/print.css);</style>
<link rel="icon" href="{$config{secure_url}}/favicon.ico" type="image/x-icon"/>
<link rel="shortcut icon" href="{$config{secure_url}}/favicon.ico" type="image/x-icon"/>
<link rel="Top" href="{$config{frontpage}}"/>
<link rel="Search" href="{$config{perl_url}}/search"/>
<epc:pin ref="head"/>
</head>
<body bgcolor="#ffffff" text="#000000">
div class="ep_noprint">
<noscript><style type='text/css'>@import url(<epc:print expr="$config{secure_url}"/>/style/nojs.css);</style></noscript>
</div>
<epc:pin ref="pagetop"/>
div class="ep_tm_header ep_noprint">
div class="ep_tm_logo"><a href="{$config{frontpage}}"><img alt="Logo" src="{$config{secure_url}}{$config{site_logo}}" /></a></div>

also change the link to the EPrints logo in the footer:

<a href="http://eprints.org/software/"><img src="{$config{secure_url}}/images/eprintslogo.gif" border="0"/></a>

We now need to modify 'generate_static' to create the secure_auto.css file as well as auto.css. The relevant section should be modified like this:

# do the magic auto.js and auto.css
my $js = "";
my $css = "";
my $secure_css ="";
my $fn;
my $base_url = $session->get_repository->get_conf( "base_url" );
my $secure_url = $session->get_repository->get_conf( "secure_url" );
foreach my $target ( sort keys %{$map} )
{
if( $target =~ m/(\/style\/auto\/.*\.css$)/ )
{
$css .= "\@import url($base_url$1);\n";
$secure_css .= "\@import url($secure_url$1);\n";
}
if( $target =~ m/(\/javascript\/auto\/.*\.js$)/ )
{
$fn = $map->{$target};
open( JS, $fn ) || EPrints::abort( "Can't read $fn: $!" );
$js .= "\n\n\n/* From: $fn */\n\n";
$js .= join( "", <JS> );
close JS; }
}

$fn = "$base_target_dir/style/auto.css";
open( CSS, ">$fn" ) || EPrints::abort( "Can't write $fn: $!" );
$wrote_files->{$fn} = 1;
print CSS $css;
close CSS;

$fn = "$base_target_dir/style/secure_auto.css";
open( CSS, ">$fn" ) || EPrints::abort( "Can't write $fn: $!" );
$wrote_files->{$fn} = 1;
print CSS $secure_css;
close CSS;

Re-run generate_static repos1.

=== Missing Images ===

A number of image links will be broken because eprints is looking for them on urlpath rather than on secureurl. In some cases this can be fixed by replacing urlpath with secureurl in the code, but some phrases may appear on both secure and insecure pages. Therefore we also need a solution which can be evaluated by a epin in a template. The cleanest way I could find of doing this is as follows:

Add two methods to EPrints::Session

######################################################################
=pod

=item $foo = $session->get_baseurl()

Gets the base url for images, depending on whether the session is secure
or not (N.B. by secure we mean EPrints_secure is yes)
Added by CSH 26 June 2007

=cut
######################################################################
sub get_baseurl
{
my( $self ) = @_;

my $esec = $self->get_request->dir_config( "EPrints_Secure" );
if( defined $esec && $esec eq "yes" )
{
return $self->get_repository->get_conf( "securepath" );
}
else
{
return $self->get_repository->get_conf( "base_url" );
}
}

######################################################################
=pod

=item $foo = $session->get_imageurl()

Gets the base url for images, depending on whether the session is secure
or not (N.B. by secure we mean EPrints_secure is yes)
Added by CSH 26 June 2007

=cut
######################################################################
sub get_imageurl
{
my( $self ) = @_;

return $self->get_baseurl."/style/images/";
}

Search through the eprints code for every occurrence of the string /style/images/ and replace with a call to get_imageurl

e.g. In /opt/eprints/perl_lib/EPrints/Plugin/Screen/Items.pm, change the line

my $imagesurl = $self->{session}->get_repository->get_conf( "urlpath" )."/style/images";

to

my $imagesurl = $self->{session}->get_imageurl;

We will add a variable called baseurl to the variables available in a script:

In the execute method of EPrints::Script, add:

$state->{baseurl} = [$state->{session}->get_baseurl, "STRING" ];

before the run command is called on the compiler. It will now be possible to get the url for images in a phrase through {$baseurl}

In /opt/eprints3/lib/lang/en/phrases/system.xml, change the links to images in the following phrases to use $baseurl

sys:ep_form_required
Plugin/InputForm/Surround/Default:show_help
Plugin/InputForm/Surround/Default:hide_help
lib/session:show_help
lib/session:hide_help

e.g. the ep_form_required phrase becomes:

<epp:phrase id="sys:ep_form_required"><img src="{$baseurl}/style/images/required.png" border="0" class="ep_required" alt="Required"/> <epc:pin name="label"/></epp:phrase>

If some repositories aren't using https, you may prefer to override these phrases on a per repository basis.

== Troubleshooting ==

Some common problems and solutions:

=== File does not exist: /htdocs ===

In the log file you may see messages like:

File does not exist: /htdocs

This may be generated by https pages with invalid links to images (e.g. /images instead of /repos1/images) if no DocumentRoot is set for the https virtual host. Note that if we had only one repository per https address we could use DocumentRoot to point to DocumentRoot /opt/eprints3/archives/ARCHIVEID/html/en/ (as suggested by Peter Schober) but this wont work on a per repository base as you can’t put DocumentRoot in a Location block.

=== EPrint 1 has no directory set ===

If you get the message “EPrint 1 has no directory set. This is very dangerous as EPrints has no idea where to write files for this eprint. This may imply a buggy import tool or some other cause of corrupt data.”, it is most probably caused by the web server user having failed to create a target subdirectory for the new eprint under archives/archivename/documents/disk0/... due to insufficient file system permissions. Perhaps you forgot to set Apache to run as eprints:eprints (or alternatively, add the Apache user to the eprints group).

=== Other ===

Remember to check that the EPrints_Dir_SecuredCGI and EPrints_Dir_Documents variables are set and cookie_domain is securehost not host.

== Useful info ==

You can set $imagesurl to be secure or insecure at runtime with some code like this (taken from MetaField.pm)

my $esec = $session->get_request->dir_config( "EPrints_Secure" );
if( defined $esec && $esec eq "yes" )
{
$imagesurl = $session->get_repository->get_conf( "securepath" )."/style/images";
}

EPrints Glossary

Ap1e26 — Wed, 14 Oct 2026 09:06:52 GMT

Latest tool

← Older revision		Revision as of 09:06, 14 October 2026
(One intermediate revision by the same user not shown)
Line 167:		Line 167:

	=== Dynamic Pages ===		=== Dynamic Pages ===
	Dynamic pages are pages that are generated each time the page is loaded. The most common example of this is the search pages. Plugins may add additional pages, eg: irstats2 adds dynamic stats page.		Dynamic pages are pages that are generated each time the page is loaded. The most common example of this is the search pages, another example is the [[#Latest tool \| Latest tool]] page. Plugins may add additional pages, eg: irstats2 adds dynamic stats page.

	== E ==		== E ==
Line 380:		Line 380:
	== L ==		== L ==
	=== Latest tool ===		=== Latest tool ===
	The latest tool is a piece of functionally that allows JavaScript to be used to include a dynamically updating list of the latest [[#EPrint\|eprints]] to be put into the [[#Live archive\|live archive]] on to a [[#Static page\|static page]] like the [[#Homepage\|homepage]]. This is provided through a script that can be requested at the equivalent following URL:		The latest tool is a piece of functionally that allows JavaScript to be used to include a dynamically updating list of the latest [[#EPrint\|eprints]] from a [[#Dynamic Pages \| dynamic page]] to be put into the [[#Live archive\|live archive]] on to a [[#Static page\|static page]] like the [[#Homepage\|homepage]]. This is provided through a script that can be requested at the equivalent following URL:
	http://example.eprints.org/cgi/latest_tool		http://example.eprints.org/cgi/latest_tool
	It can be configured in the archive's ''cfg/cfg.d/[[latest_tool.pl]]'' to set the number of eprints shown and the [[#Citation\|citation]] style used.		It can be configured in the archive's ''cfg/cfg.d/[[latest_tool.pl]]'' to set the number of eprints shown and the [[#Citation\|citation]] style used.

Branding/Logos

Ap1e26 — Wed, 14 Oct 2026 09:01:20 GMT

Dynamic pages

← Older revision		Revision as of 09:01, 14 October 2026
Line 30:		Line 30:
	run generate_views		run generate_views

	=== [[EPrints_Glossary# \| Dynamic pages]] ===		=== [[EPrints_Glossary#Dynamic Pages \| Dynamic pages]] ===

	run force_config_reload or resart the webserver		run force_config_reload or resart the webserver

EPrints Glossary

Ap1e26 — Wed, 14 Oct 2026 09:00:52 GMT

← Older revision		Revision as of 09:00, 14 October 2026
Line 165:		Line 165:
	=== Documents directory ===		=== Documents directory ===
	This is a directory found under the [[#Archive\|archive's]] directory structure, (i.e. ''EPRINTS_PATH/archives/ARCHIVEID/documents/''). This is where the uploaded [[#Document\|documents]] for an [[#EPrint\|eprint]] are stored under the latter's own sub-directory (e.g. eprint 1234 has documents sub-directory ''documents/00/00/12/34/''). Each document is stored in its own two-digit sub-directory based on its ''pos'' [[#Metadata field\|metadata field]], which is zero-padded if the number is less than 10. The sub-directory also stores derived "documents" for those uploaded (e.g. preview and thumbnail images). It also stores [[#Revision file\|revision files]] in the eprint's own ''revisions'' sub-directory.		This is a directory found under the [[#Archive\|archive's]] directory structure, (i.e. ''EPRINTS_PATH/archives/ARCHIVEID/documents/''). This is where the uploaded [[#Document\|documents]] for an [[#EPrint\|eprint]] are stored under the latter's own sub-directory (e.g. eprint 1234 has documents sub-directory ''documents/00/00/12/34/''). Each document is stored in its own two-digit sub-directory based on its ''pos'' [[#Metadata field\|metadata field]], which is zero-padded if the number is less than 10. The sub-directory also stores derived "documents" for those uploaded (e.g. preview and thumbnail images). It also stores [[#Revision file\|revision files]] in the eprint's own ''revisions'' sub-directory.

			=== Dynamic Pages ===
			Dynamic pages are pages that are generated each time the page is loaded. The most common example of this is the search pages. Plugins may add additional pages, eg: irstats2 adds dynamic stats page.

	== E ==		== E ==

Branding/Logos

Ap1e26 — Wed, 14 Oct 2026 08:55:46 GMT

Cause the new template to be applied

← Older revision		Revision as of 08:55, 14 October 2026
(3 intermediate revisions by the same user not shown)
Line 19:		Line 19:
	This is slightly different for each part of the site...		This is slightly different for each part of the site...

	===Static pages===		=== [[EPrints_Glossary#Static page \| Static pages]] ===

	run generate_static		run generate_static

	===Abstract pages===		=== [[EPrints_Glossary#Abstract page \| Abstract pages]]===

	run generate_abstracts		run generate_abstracts

	===View pages===		=== [[EPrints_Glossary#EPrint view page \| View pages]] ===

	run generate_views		run generate_views

	===Dynamic pages===		=== [[EPrints_Glossary# \| Dynamic pages]] ===

	run force_config_reload or resart the webserver		run force_config_reload or resart the webserver

Template:Manual

Ap1e26 — Wed, 14 Oct 2026 08:16:27 GMT

← Older revision		Revision as of 08:16, 14 October 2026
Line 10:		Line 10:
	**** [[Required software]]		**** [[Required software]]
	** [[Upgrading\|Upgrading EPrints]]		** [[Upgrading\|Upgrading EPrints]]
	** [[~~Getting Started~~]]		** [[Setting up an Archive]]
	** [[Backups]]		** [[Backups]]
	** [[Troubleshooting]]		** [[Troubleshooting]]

Getting Started

Ap1e26 — Wed, 14 Oct 2026 08:15:28 GMT

Ap1e26 moved page Getting Started to Setting up an Archive Change of name to clarify page content

New page

{{manual}}
[[Category:Manual]]

==Creating an Archive==

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

===Creating MySQL eprints user===
If you are running a modern version of Linux (e.g. Red Hat Enterprise Linux 9+ or Ubuntu 20.04+), the eprints user will not be able to connect to the MySQL database as the root user without a password. Therefore, before running "epadmin create" later in these instructions make sure you switch to the root user, open the MySQL client and run the following commands, (substituting the password (i.e. 'changeme') appropriately):
CREATE USER 'eprints'@'localhost' IDENTIFIED by 'changeme';
GRANT ALL PRIVILEGES ON *.* TO 'eprints'@'localhost' WITH GRANT OPTION;
When you are asked for the '''Database Superuser Username''' and '''Database Superuser Password''' be sure to use the username and password set above. If you are running older version of Linux where you have not needed to do the above steps. You can probably use the default options for these to steps.

===Creating the Archive===
Make sure MySQL is actually running.

Change to your "eprints" user.

Change directory to the eprints directory (<tt>/opt/eprints3</tt> by default) and run the '''EXACT''' following command to create a research publications archive. (You will be prompted to answer various questions about the configuration of your archive):
bin/epadmin create pub

If you don't want a research publications archive, in the above command use <code>zero</code> instead of <code>pub</code>. This will create a very basic repository, which can either store very generic items or can be more greatly customised as it does not have some of the intentional restrictions that come with a Research Publications repository. Other flavours of repository may be available but these will have to have be added their <tt>FLAVOUR_lib</tt> to the <tt>EPRINTS_PATH/flavours/</tt> directory. If you run just <code>bin/epadmin create</code> without a further parameter or one that is not recognised, the command should suggest what types (flavours) of repository archive are available.

===Creating the Database Tables and Website ===
These will have been created when you created the archive.

==Running a Live Archive==
===Creating a crontab===
When you create an archive it will start out as a development system while you learn how to set it up (and your manager keeps changing his mind) but at some point (hopefully) you will declare your archive open for business.

At this point you should schedule certain scripts to run periodically. The best way to do this is to use "cron" which is an integral part of most UNIX systems.

To set up cron, run (as the eprints user):
% crontab -e

Exactly what to add to the cron table is described in the following sections - "Browse Views" and "Subscriptions".

There should be one set of crontab entries per archive.

Here is an example crontab template. <code>EPRINTS_PATH</code> and <code>ARCHIVE_ID</code> should be replaced as appropriate.

{{template:EPrints_Crontab_Template}}

For more information about [[EPrints Cron Jobs|cron jobs for EPrints, click here]].

===Backups===
You should also have made sure that the system is being properly backed up. This is gone into in more detail elsewhere in the documentation.

===OAI===
We would also encourage you to configure the OAI support for your archive and register it. It's quite easy - pretty much fill in the blanks in the ArchiveOAIConfig.pm file in the archive configuration directory.

EPrints 2.1 support OAI versions 1 and 2 at URL paths /perl/oai and /perl/oai2.

Once you register your archive (at http://www.openarchives.org) various search systems will be able to collect the metadata (titles, authors, abstract etc.) and allow more people to find records in your archive.

See http://www.openarchives.org/ for more information on the OAI protocol. For more information setting up the OAI interface archive see the section in this documentation about Configuring an Archive.

==Browse Views==
Once every so often you should run the "generate_views" script on each archive in your system to regenerate the browse views section of the site.

This is a set of static pages. By default one per subject, and one per year (only years with papers in that year not EVERY year ever!). Some users prefer to browse the system than search it. This also gives search engines a way to reach, and index, the abstract pages.

See the ArchiveConfig.pm config notes on how to edit the views it generates.

See the How-To section for some suggestions on how to set up views.

===But I don't want this feature...===
If you don't want to use this feature: don't, it's your archive. Remove the link from the template and front page. Don't run the generate_views script.

===Setting it up===
This is best done by using the UNIX "cron" command (as user "eprints"). Cron will email "eprints" on that machine with the output, so best use the --quiet option so it only bothers you with errors.

How often you want to run this depends on the size of your archive, and how fast the contents changes. This feature is roughly order "n". Which means if you double the number of items in your archive then you double the time it takes to run (ish).

Once an hour would seem a good starting point. If your archive gets real big, say more than 10000 records, then maybe once a day is more realistic - the one thing that you don't want to happen is for a new generate_views to start before the old one finishes as they will mess up each others output.

Run generate_views on the command line to find out how long it takes.

and add the line
23 * * * * /opt/eprints2/bin/generate_views I<archiveid>

This runs at 23 minutes past each hour. If you have more than one archive, don't make them all start rebuilding stuff at the same time, stagger it. Otherwise once an hour everything will slow down as it fights to run several intensive scripts at once.

See the crontab man page <tt>man 5 crontab</tt> for more information on using cron.

==Default Configuration==
EPrints configures a new archive with a set of metadata fields aimed at an archive of research papers.

The initial "types" of eprint (book, poster, conference paper) are configured in metadata-types.xml

The initial subjects are a subset of the library of congress subjects. Feel free to totally replace them with your own subjects, but the more standard your subject tree the more useful your metadata will be to other people.

The authors and editors have the "hasid" option set which allows people to optionally use a unique id for a person in addition to their name (names are NOT unique!) - this can be useful for generating "CV" pages (see the views how-to) and possibly for generating statistics. Without it you will never be sure which "John Smith" wrote that paper. If you don't like this feature remove the "hasid" from the authors and editors - this will require you to recreate the tables, erasing the archive, so decide before you start. If you want to be more clear about what information goes in that field, edit the phrases <tt>eprint_fieldname_authors_id</tt> and <tt>eprint_fieldname_editors_id</tt> in the archive phrase file(s).

In general: Change it! It's not a recommended system setup, just a good starting point.

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

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

Create an EPrint Repository

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

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

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

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

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

Please enter the fully qualified hostname of the repository.

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

Example: testrepo.footle.ac.uk

Hostname? testprint

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

Webserver Port [80] ?

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

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

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

Alias (enter # when done) [#] ?

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

Path [/] ?

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

HTTPS Hostname [] ?

Administrator Email? someone@example.com

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

Archive Name [Test Repository] ?

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

Configure database? [yes] ?

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

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

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

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

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

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

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

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

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

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

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

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

You must restart apache for any changes to take effect!

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

Now make any required changes to the cfg files.

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

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

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

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

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

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

-bash-4.1$

</pre>

==New Configurations==
If you are setting up more than one archive which are related to each other, a "community", you may wish to establish common subjects and metadata.

Removing and adding types is easy. Removing and adding fields is a bit more work. All "screen" names of values are stored in the archives own "phrase file" which comes with phrases for the default config.

If you create a good default configuration for a different purpose or language(s) (and would like to share it), please contact the eprints admin who may want to put it online as an example or even include it as an alternate default in a later version.

Installing an EPM

Ap1e26 — Tue, 13 Oct 2026 13:50:43 GMT

← Older revision		Revision as of 13:50, 13 October 2026
Line 1:		Line 1:
			[[Category:Howto]]
	== Important ==		== Important ==
	Broadly EPMs have been superseded by Ingredients and should be avoided. If you find you must install one, this guide aims to help.		Broadly EPMs have been superseded by Ingredients and should be avoided. If you find you must install one, this guide aims to help.

Installing Ingredients

Ap1e26 — Tue, 13 Oct 2026 13:49:57 GMT

← Older revision		Revision as of 13:49, 13 October 2026
Line 1:		Line 1:
	[[Category:Howto]]		[[Category:Howto]]
	An '''Ingredient''' in [[EPrints]] is a modular package or extension (such as `image_tiles`) that adds specific functionality to an EPrints repository flavour.		An '''Ingredient''' in EPrints is a modular package or extension (such as `image_tiles`) that adds specific functionality to an EPrints repository flavour.

	This guide explains how to install an ingredient by cloning its source repository and registering it in your flavour's inclusion configuration file.		This guide explains how to install an ingredient by cloning its source repository and registering it in your flavour's inclusion configuration file.

Installing Ingredients

Ap1e26 — Tue, 13 Oct 2026 13:49:18 GMT

Created page with "Category:Howto An '''Ingredient''' in EPrints is a modular package or extension (such as `image_tiles`) that adds specific functionality to an EPrints repository flavo..."

New page

[[Category:Howto]]
An '''Ingredient''' in [[EPrints]] is a modular package or extension (such as `image_tiles`) that adds specific functionality to an EPrints repository flavour.

This guide explains how to install an ingredient by cloning its source repository and registering it in your flavour's inclusion configuration file.

== Clone the Ingredient Repository ==
Navigate to your EPrints ingredients directory (`/opt/eprints3/ingredients/`) and clone the git repository.

For example, to install the '''image_tiles''' ingredient:

<syntaxhighlight lang="bash">
cd /opt/eprints3/ingredients/
git clone https://github.com/eprints/image_tiles
</syntaxhighlight>

''Note: Ensure the resulting destination directory path matches `/opt/eprints3/ingredients/image_tiles`.''

== Register the Ingredient in the Flavour Include File ==
To activate the ingredient, you must declare it in your flavour's `inc` configuration file located at:

`/opt/eprints3/flavours/<flavour_name>_lib/inc`
<i>the most common flavour name is pub_lib

# Open the `inc` file in a text editor (e.g., `nano` or `vim`):
#: <syntaxhighlight lang="bash">nano /opt/eprints3/flavours/<flavour_name>_lib/inc</syntaxhighlight>
# Add the ingredient path line above the site library inclusion line (typically `#site_lib` or `site_lib`):
#: <syntaxhighlight lang="text">
ingredients/image_tiles
</syntaxhighlight>

=== Configuration File Example ===
Your `inc` file structure should look similar to this:

<syntaxhighlight lang="text">
# Active ingredients
ingredients/image_tiles

# Site core library
site_lib
</syntaxhighlight>

== Step 3: Restart Apache ==
For EPrints to pick up the changes to the flavour configuration, restart the web server:

<syntaxhighlight lang="bash">
sudo systemctl restart apache2
</syntaxhighlight>

Upgrading

Ap1e26 — Tue, 13 Oct 2026 13:05:07 GMT

← Older revision		Revision as of 13:05, 13 October 2026
Line 1:		Line 1:
	[[Category:Upgrading]]		[[Category:Upgrading]]
			{{manual}}
	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 a tagged release from [https://github.com/eprints/eprints3.4/ EPrints 3.4 GitHub repository] or upgrading using source tarballs available on [https://files.eprints.org/ files.eprints.org]. 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]).		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 a tagged release from [https://github.com/eprints/eprints3.4/ EPrints 3.4 GitHub repository] or upgrading using source tarballs available on [https://files.eprints.org/ files.eprints.org]. 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]).

Upgrading between EPrints 3.3 Versions

Ap1e26 — Tue, 13 Oct 2026 13:04:53 GMT

← Older revision		Revision as of 13:04, 13 October 2026
Line 1:		Line 1:
	[[Category:Upgrading]]		[[Category:Upgrading]]
	~~{{manual}}~~
	== Upgrade between same series versions of EPrints ==		== 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.		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.

Upgrading

Ap1e26 — Tue, 13 Oct 2026 13:04:19 GMT

From a source tarball

← Older revision		Revision as of 13:04, 13 October 2026
(One intermediate revision by the same user not shown)
Line 20:		Line 20:
	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.		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 GitHub release ==		= From GitHub release =
	'''N.B. These instructions are a work in progress.'''		'''N.B. These instructions are a work in progress.'''

Line 37:		Line 37:


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

Line 67:		Line 67:
	/opt/eprints3/bin/indexer start		/opt/eprints3/bin/indexer start

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

Line 112:		Line 112:
	/opt/eprints3/bin/indexer start		/opt/eprints3/bin/indexer start

	== From a source tarball ==		= 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.		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.tar.gz /home/eprints/

Upgrading between EPrints 3.4 versions

Ap1e26 — Tue, 13 Oct 2026 13:03:22 GMT

Redirected page to Upgrading

Show changes

Upgrading

Ap1e26 — Tue, 13 Oct 2026 13:02:14 GMT

Show changes

Upgrading between EPrints 3.3 Versions

Ap1e26 — Tue, 13 Oct 2026 13:01:44 GMT

← Older revision		Revision as of 13:01, 13 October 2026
Line 3:		Line 3:
	== Upgrade between same series versions of EPrints ==		== 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.		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.
	~~[[Upgrading between EPrints 3.3 Versions]]~~

	=== From a Linux Package Manager ===		=== From a Linux Package Manager ===

Upgrading between EPrints 3.3 Versions

Ap1e26 — Tue, 13 Oct 2026 13:01:32 GMT

Created page with "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..."

New page

[[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.
[[Upgrading between EPrints 3.3 Versions]]

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

Installing an EPM

Ap1e26 — Tue, 13 Oct 2026 12:59:53 GMT

Integration with the Archive

← Older revision		Revision as of 12:59, 13 October 2026
(One intermediate revision by the same user not shown)
Line 3:		Line 3:

	== Installing from GitHub repository ==		== Installing from GitHub repository ==
	1. Clone from Github the Bazaar plugin repository (e.g. https://github.com/eprints/reports.git) to /opt/eprints3/lib/epm/ and fetch the required version~~. (If you are installing a different version to what they have already installed you will need to take great care when '''Integration with the Archive''')~~.		1. Clone from Github the Bazaar plugin repository (e.g. https://github.com/eprints/reports.git) to /opt/eprints3/lib/epm/ and fetch the required version.
	cd /opt/eprints3/lib/epm/		cd /opt/eprints3/lib/epm/
	git clone https://github.com/eprints/reports.git		git clone https://github.com/eprints/reports.git
Line 11:		Line 11:
	2. Run the /opt/eprints3/ingredients/bazaar/tools/epm command to link the library from /opt/eprints3/lib/epm/ in the appropriate locations under /opt/eprints3/lib/		2. Run the /opt/eprints3/ingredients/bazaar/tools/epm command to link the library from /opt/eprints3/lib/epm/ in the appropriate locations under /opt/eprints3/lib/
	/opt/eprints3/ingredients/bazaar/tools/epm link_lib reports # EPrints 3.4.6+		/opt/eprints3/ingredients/bazaar/tools/epm link_lib reports # EPrints 3.4.6+
	/opt/eprints3/~~site_lib~~/tools/epm ~~link_lib~~ reports ~~# EPrints 3~~.4.5-
			== Integration with the Archive ==
			1. Enable the plugin using tools/epm
			/opt/eprints3/ingredients/bazaar/tools/epm enable <ARCHIVE_ID> <PLUGIN_ID>
			<i>Note: <code>PLUGIN_ID</code> in our example is <code>reports</code></i>

			2. Where any warnings are produced compare the current and .epmnew version of a file and reconcile any differences. Removing the .epmnew file when you are done.

Installing an EPM

Ap1e26 — Tue, 13 Oct 2026 12:55:55 GMT

Created page with "== Important == Broadly EPMs have been superseded by Ingredients and should be avoided. If you find you must install one, this guide aims to help. == Installing from GitHub r..."

New page

== Important ==
Broadly EPMs have been superseded by Ingredients and should be avoided. If you find you must install one, this guide aims to help.

== Installing from GitHub repository ==
1. Clone from Github the Bazaar plugin repository (e.g. https://github.com/eprints/reports.git) to /opt/eprints3/lib/epm/ and fetch the required version. (If you are installing a different version to what they have already installed you will need to take great care when '''Integration with the Archive''').
cd /opt/eprints3/lib/epm/
git clone https://github.com/eprints/reports.git
cd reports
git checkout v3.2.1

2. Run the /opt/eprints3/ingredients/bazaar/tools/epm command to link the library from /opt/eprints3/lib/epm/ in the appropriate locations under /opt/eprints3/lib/
/opt/eprints3/ingredients/bazaar/tools/epm link_lib reports # EPrints 3.4.6+
/opt/eprints3/site_lib/tools/epm link_lib reports # EPrints 3.4.5-

Main Page

LukeWallin — Mon, 12 Oct 2026 13:30:25 GMT

Getting Started

← Older revision		Revision as of 13:30, 12 October 2026
Line 39:		Line 39:
	* [[:Category:Plugins\|Plugins and Bazaar packages for EPrints]]		* [[:Category:Plugins\|Plugins and Bazaar packages for EPrints]]
	* [[:Category:Training Video\|EPrints Training Course]]		* [[:Category:Training Video\|EPrints Training Course]]
	* [[Staying Online with AI Bots]]		* [[Abubis - Staying Online with AI Bots]]

	==Getting Support==		==Getting Support==

Staying Online with AI Bots

LukeWallin — Mon, 12 Oct 2026 13:30:05 GMT

LukeWallin moved page Staying Online with AI Bots to Abubis - Staying Online with AI Bots

← Older revision		Revision as of 13:30, 12 October 2026
(7 intermediate revisions by the same user not shown)
Line 2:		Line 2:

	From 2025(ish) onwards, EPrints instances can struggle to stay online from DDOS-like behaviour that is flung at it regularly.		From 2025(ish) onwards, EPrints instances can struggle to stay online from DDOS-like behaviour that is flung at it regularly.

			EPrints Services have been working on a solution that uses Anubis to attempt filter out bots for specific pages, and nginx to add a cache and apply rate and connection limiting. Our solution is tailored to our hosting infrastructure, but should be relatively easy to adapt to a bespoke EPrints installation. This page documents how the solution works and how it is configured.

			=== Our Solution ===

			The ingredient [https://github.com/eprints/anubis "Anubis"] contains our solution with Anubis and Nginx. Its README will be the most up to date source of information, therefore this will only summarise.

			* EPrints is run on its own internal instance of Apache, because it is unstable in Apache's multithreaded mode, and the layers in front exacerbate the effects of a segfault.
			* Apache is used as the front webserver (listening on port 80/443) because this is currently the only way to support Shibboleth Single Sign On and SSL is already configured for Apache.
			* Nginx is used instead of Apache because it natively supports more open connections than Apache (originally it was intended to be the front facing webserver) and it has some very useful rate limiting and caching features.
			* In order to support not caching logged in users, the ingredient has some fixes for core EPrints code for setting and unsetting session cookies. Hopefully the next (3.4.9) release of EPrints will include these fixes.

Staying Online with AI Bots

LukeWallin — Mon, 12 Oct 2026 11:00:33 GMT

Created page with "== Hardening your EPrints instance so it can survive the onslaught of bizarre behaviour from (presumed) AI bots. == From 2025(ish) onwards, EPrints instances can struggle to..."

New page

== Hardening your EPrints instance so it can survive the onslaught of bizarre behaviour from (presumed) AI bots. ==

From 2025(ish) onwards, EPrints instances can struggle to stay online from DDOS-like behaviour that is flung at it regularly.

Main Page

LukeWallin — Mon, 12 Oct 2026 10:56:44 GMT

Getting Started

← Older revision		Revision as of 10:56, 12 October 2026
Line 39:		Line 39:
	* [[:Category:Plugins\|Plugins and Bazaar packages for EPrints]]		* [[:Category:Plugins\|Plugins and Bazaar packages for EPrints]]
	* [[:Category:Training Video\|EPrints Training Course]]		* [[:Category:Training Video\|EPrints Training Course]]
			* [[Staying Online with AI Bots]]

	==Getting Support==		==Getting Support==

Upgrading

Ap1e26 — Mon, 12 Oct 2026 09:27:25 GMT

Upgrade between same series versions of EPrints

← Older revision		Revision as of 09:27, 12 October 2026
(One intermediate revision by the same user not shown)
Line 3:		Line 3:
	== Upgrade between same series versions of EPrints ==		== 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.		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.
			[[Upgrading between EPrints 3.3 Versions]]

	=== From a Linux Package Manager ===		=== From a Linux Package Manager ===
Line 102:		Line 103:
	</ol>		</ol>

	== Upgrading to EPrints to 3.3 ==		== Upgrading to EPrints 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 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.1]]