Difference between revisions of "Upgrading 3.3.12+ to 3.4"

From EPrints Documentation
Jump to: navigation, search
m
 
(23 intermediate revisions by 5 users not shown)
Line 1: Line 1:
These instructions help you upgrade EPrints 3.3.12+ to 3.4 while keeping all your eprints, documents and local configuration changes.
+
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.12+ was installed using a tarball (tar.gz) in /opt/eprints3. These instructions assumes Centos 7 OS.
+
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=
 
=Upgrade from Tarball=
Line 7: Line 7:
 
==Pre-upgrade==
 
==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 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, as root use CPAN to install LWP::Authen::OAuth as this is no longer in perl_lib.
+
* 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
 
  cpan LWP::Authen::OAuth
* Note down the enabled bazaar package on your repository.
+
* Download each of the Bazaar plugins you have installed as EPM files from your existing repository.
* Make a backup of your local configs.  
+
* Make a backup of your local configurations.
  
 
==Process==
 
==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]
We will move your existing eprints 3.3.12+ installation from /opt/eprints3/ to /opt/eprints3.3, install eprints 3.4, then migrate your configurations into EPrints 3.4.  
+
<br>
as root:
+
'''as root'''
 
  apachectl stop
 
  apachectl stop
 
  cd /opt
 
  cd /opt
 +
eprints3/bin/epindexer stop
 
  mv eprints3 eprints3.3
 
  mv eprints3 eprints3.3
  
* Download EPrints 3.4 core and publication flavour tarball and install them [http://files.eprints.org/]
+
* Download EPrints 3.4 core and publication flavour tarball and install them from [http://files.eprints.org/ Files.eprints.org] with
  as root:
+
wget https://files.eprints.org/2789/1/eprints-3.4.5.tar.gz
 +
  wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz
 +
'''as root'''
 
  cd /root
 
  cd /root
  tar xvzf eprints-3.4.0-rc1.tar.gz
+
  tar xvzf eprints-3.4.5.tar.gz
  tar xvzf eprints-3.4.0-rc1-flavours.tar.gz
+
  tar xvzf eprints-3.4.5-flavours.tar.gz
  cd eprints-3.4.0
+
 
 +
* Have a look to <code>/root/eprints-3.4.5/INSTALL</code> for some local adaption options.
 +
'''as root'''
 +
  cd eprints-3.4.5
 
  ./configure
 
  ./configure
 
  make install
 
  make install
  
 
* Move your current repository from 3.3 to 3.4
 
* Move your current repository from 3.3 to 3.4
as root user:
+
'''as root'''
 
  cd /opt
 
  cd /opt
 
  mv eprints3.3/archives/ARCHIVENAME eprints3/archives/
 
  mv eprints3.3/archives/ARCHIVENAME eprints3/archives/
After moving, make sure all files inside /opt/eprints3 are still owned by eprints user and belongs to eprints group.
+
* 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
  
* In /opt/eprints3/archives/ARCHIVENAME/, create cfg/cfg.d/00_flavour.pl and set the appropriate flavour, typically 'pub':
+
* Create <code>/opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl</code> to set the appropriate flavour, typically 'pub', i.e.
  $c->{flavour} = 'pub';
+
  echo "\$c->{flavour} = 'pub';" > /opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl
  
* create a symbolic link to default.xml  
+
* 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/
 
  cd /opt/eprints3/archives/ARCHIVENAME/cfg/templates/ (or /opt/eprints3/archives/ARCHIVENAME/cfg/lang/en/templates/
 
  ln -s default.xml default_internal.xml
 
  ln -s default.xml default_internal.xml
  
* Audit each of their local config files against the pub_lib flavours config filesThe first Diff below will identify all the files that are the same.  If so delete the ones in archives/ARCHIVENAME/cfg/cfg.d/.  There is a good chance you will not find any. The second diff 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.
+
* 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/
 
  cd /opt/eprints3/
 
  diff -rs archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ are identical$'
 
  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$'
 
  diff -rq archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ differ$'
  
* Compare archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl with flavours/pub_lib/cfg/cfg.d/eprint_fields_pub.pl,
+
<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>
** If these are different and fields are present in eprint_fields_pub.pl and not eprint_fields.pl or the definitions (e.g. type, options, etc.)  for the same field are different then:
+
<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>
**# Copy flavours/pub_lib/cfg.d/eprint_fields_pub.pl to their archive's cfg/cfg.d/
+
<li>Copy <code>flavours/pub_lib/cfg.d/eprint_fields_pub.pl</code> to their archive's <code>cfg/cfg.d/</code>.
**# Modify the fields in their archive's cfg/cfg.d/eprint_fields_pub.pl where they have different definitions (e.g. type, options, etc.) to those in eprint_fields.pl
+
<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>.
**# Remove all fields in their archive's cfg/cfg.d/eprint_fields.pl where they also occur in their archive's cfg/cfg.d/eprint_fields_pub.pl
+
<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>
** If there are only additional fields in archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl then just do the last step.
+
<li>If there are only additional fields in <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> then just do the last step.
** If the two files are identical then you need to nothing.  However, this is extremly unlikely.
+
<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)
* As the eprints user, run epadmin update 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
 
  /opt/eprints3/bin/epadmin update ARCHIVENAME
  
* Generate Apache configuration and as root test (fixing any issues) and restart Apache.
+
* 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
+
  /opt/eprints3/bin/generate_apacheconf --system --replace ARCHIVENAME
 +
'''as root'''
 
  apachectl configtest
 
  apachectl configtest
 
  apachectl restart
 
  apachectl restart
  
* Once confirming that EPrints is generally working.  Go to Admin-> Bazaar then install the required bazaar packages. 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:
+
* 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.  
  mv z_orcid_support.pl z_orcid_support.pl.disabled
+
 
mv zz_hefce_oa_fields.pl zz_hefce_oa_fields.pl.disabled
+
* Move back the files you renamed to FILENAME''.disabled'' earlier, the epindexer into service and reload Apache
  mv zz_rioxx2.pl zz_rioxx2.pl.disabled
+
'''as root'''
  mv z_meprints.pl z_meprints.pl.disabled
+
  /opt/eprints3/bin/epindexer start
 +
  apachectl graceful
  
* Finally, run generate statics to make sure all pages are regenerates with any changes to configuration.
+
* Finally, run <code>generate_static</code> to make sure all pages are regenerated with any changes to configuration.
   /opt/eprints3/bin/generate_static ARCHIVE_NAME
+
   /opt/eprints3/bin/generate_static ARCHIVEID
  
 
==Notes==
 
==Notes==
* 3.4 does not automatically update an archive's html/en/ files. If there are any bugs with broken Javascript or unexpected CSS, try deleting the archives html/en/javascript/auto.js or html/en/style/auto.css.  Similarly if a static page cannot be changed try deleting it under the archive's html/en/ or running generate_static.
+
* 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 message like:  
+
* 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::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.
 
   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 perl_lib, while the PIRUS.pm is in pub_lib.  
+
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 "use" the parent module before the ISA line:
+
Just need to <code>use</code> the parent module before the <code>ISA</code> line:
 
  use EPrints::Plugin::Event;
 
  use EPrints::Plugin::Event;
 +
 +
[[Category:Upgrading]]

Latest revision as of 09:51, 22 November 2023

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 /opt/eprints3. 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 /opt/eprints3/ to /opt/eprints3.3, install eprints 3.4, then migrate your configurations into EPrints 3.4; cf. Category Installation
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 Files.eprints.org with
wget https://files.eprints.org/2789/1/eprints-3.4.5.tar.gz
wget https://files.eprints.org/2789/2/eprints-3.4.5-flavours.tar.gz

as root

cd /root
tar xvzf eprints-3.4.5.tar.gz
tar xvzf eprints-3.4.5-flavours.tar.gz
  • Have a look to /root/eprints-3.4.5/INSTALL for some local adaption options.

as root

cd eprints-3.4.5
./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 /opt/eprints3 are still owned by eprints user and belongs to eprints group, thus

as root

chown -R eprints:eprints /opt/eprints3
  • Create /opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl 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 default.xml
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:
  1. The first diff below will identify all the files that are the same. If so, delete the ones in archives/ARCHIVENAME/cfg/cfg.d/. You almost certainly should not find any, as the files in flavours/pub_lib/cfg.d will at very least have updated copyright/licensing boilerplate.
  2. The second diff 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$'
  • Compare archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl with flavours/pub_lib/cfg/cfg.d/eprint_fields_pub.pl maybe with the help of diffuse to overcome this business easier:
    • If these are different and fields are present in eprint_fields_pub.pl and not eprint_fields.pl or the definitions (e.g. type, options, etc.) for the same field are different then:
      1. Copy flavours/pub_lib/cfg.d/eprint_fields_pub.pl to their archive's cfg/cfg.d/.
      2. Modify the fields in their archive's cfg/cfg.d/eprint_fields_pub.pl where they have different definitions (e.g. type, options, etc.) to those in eprint_fields.pl.
      3. Remove all fields in their archive's cfg/cfg.d/eprint_fields.pl where they also occur in their archive's cfg/cfg.d/eprint_fields_pub.pl, no matter if already transferred due to previous item or initially the same.
    • If there are only additional fields in archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl then just do the last step.
    • If the two files are identical then you need to do nothing. However, this is extremly unlikely.
    Finally, the specification is still the same, but mostly split into two distinct files, which obey the known rule Local version overrides central one.
  • Synchronise archives/ARCHIVENAME/cfg/cfg.d/epm.pl with ingredients/bazaar/cfg.d/epm.pl, i.e. remove archives/ARCHIVENAME/cfg/cfg.d/epm.pl 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 epadmin test 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 cfg/cfg.d/ 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 epadmin update 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 generate_static 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 html/en/ files. If there are any bugs with broken JavaScript or unexpected CSS, try deleting the archives html/en/javascript/auto.js or html/en/style/auto.css. Similarly if a static page cannot be changed try deleting it under the archive's html/en/ or running generate_static.
  • 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 ./perl_lib, while the PIRUS.pm is in ./pub_lib. Just need to use the parent module before the ISA line:

use EPrints::Plugin::Event;