Upgrading between EPrints 3.4 versions - Revision history

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

2025-02-28T14:28:37Z

check of configuration files added

@@ Line 29: / Line 29: @@
 . Compare the code to see if any critical changes have been made to the core codebase:
   diff -x archives -x cfg -x tmp -rq /opt/eprints3 /home/eprints/eprints-3.4.1 | grep -v "/\(ingredients\|var\)"
 . If there are any changes check to see if the change is present in the new version of EPrints. E.g.:

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

2025-02-25T12:49:50Z

typos removed, category added, some reformatting

← Older revision		Revision as of 12:49, 25 February 2025
Line 1:		Line 1:
	This page is intended to provide guidance for those upgrading between versions of EPrints 3.4. (e.g. 3.4.1 to 3.4.2). This is generally intended for those upgrading using source tarballs available on [https://files.eprints.org/ files.eprints.org] or upgrading tagged release from [https://github.com/eprints/eprints3.4/ EPrints 3.4 GitHub repository]. However, ~~if you are upgrading through~~ EPrints [http://~~deb~~.eprints.org/3.4 ~~Deb~~] or [http://~~rpm~~.eprints.org/~~eprints3~~.4 ~~RPM~~] ~~package repostories and you experience issues this page should also contain helpful advice~~.		[[Category:Upgrading]]
			This page is intended to provide guidance for those upgrading between versions of EPrints 3.4. (e.g. 3.4.1 to 3.4.2). This is generally intended for those upgrading using source tarballs available on [https://files.eprints.org/ files.eprints.org] or upgrading tagged release from [https://github.com/eprints/eprints3.4/ EPrints 3.4 GitHub repository]. However, '''new versions of EPrints 3.4 will no longer be released as Linux packages''' (i.e. [http://rpm.eprints.org/eprints3.4 RPMs] or [http://deb.eprints.org/3.4 Debs]).

	== General Advice ==		== General Advice ==
Line 6:		Line 7:
	: This will likely have the same name as the archive.		: This will likely have the same name as the archive.
	; The documents directory		; The documents directory
	: This is the ''documents'' directory, directly under the archive's directory (i.e. ''~~<EPRINTS_PATH>~~/archives/<ARCHIVE_NAME>/'').		: This is the ''documents'' directory, directly under the archive's directory (i.e. ''/opt/eprints3/archives/<ARCHIVE_NAME>/'').
	; The Xapian index		; The Xapian index
	: This is in the ''var'' directory of the archive under the directory named or starting ''xapian''.		: This is in the ''var'' directory of the archive under the directory named or starting ''xapian''.
	; Your EPrints archive		; Your EPrints archive
	: All the directories and any files in your archive, '''except''': ''documents'' (see above), ''html'' and ''var'' (except ''xapian'', see above). If you have multiple archives be sure to backup each one.		: All the directories and any files in your archive, '''except''': ''documents'' (see above), ''html'' and ''var'' ('''except''' ''xapian'', see above). If you have multiple archives be sure to backup each one.
	; The current EPrints codebase		; The current EPrints codebase
	: In case any changes have been made to this. These may be needed if you have to rollback an upgrade or also apply these changes if they are needed in the upgraded version of EPrints. All directories in the EPrints path (e.g. /opt/eprints3~~/ or /usr/share/eprints~~/) should be backed up '''except''': ''archives'' (see above), ''debian'', ''license'', ''pod'', ''testdata'', ''tests'',''tmp'' and ''var''. No files in the top level EPrints path directory need to be backed up.		: In case any changes have been made to this. These may be needed if you have to rollback an upgrade or also apply these changes if they are needed in the upgraded version of EPrints. All directories in the EPrints path (e.g. /opt/eprints3/) should be backed up '''except''': ''archives'' (see above), ''debian'', ''license'', ''pod'', ''testdata'', ''tests'',''tmp'' and ''var''. No files in the top level EPrints path directory need to be backed up.


	Again, if you have the ability to take a virtual machine snapshot of your EPrints repository, it is worth using this to produce a clone, (if you do not already have a test or pre-production server version of your EPrints repository). This will allow you to check if you will have any snags either with the upgrade process or with the upgraded repository itself. It should also allow you to refine your upgrade schedule for your live EPrints repository to reduce the amount of scheduled downtime required.		Again, if you have the ability to take a virtual machine snapshot of your EPrints repository, it is worth using this to produce a clone, (if you do not already have a test or pre-production server version of your EPrints repository). This will allow you to check if you will have any snags either with the upgrade process or with the upgraded repository itself. It should also allow you to refine your upgrade schedule for your live EPrints repository to reduce the amount of scheduled downtime required.
Line 33:		Line 33:
	diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.1/flavours/pub_lib/inc		diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.1/flavours/pub_lib/inc
	diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.3/flavours/pub_lib/inc		diff /opt/eprints3/flavours/pub_lib/inc /home/eprints/eprints-3.4.3/flavours/pub_lib/inc
	If the ~~file~~ in <Code>/opt/eprints3/</Code> is the same as that in the latest version (e.g. <Code>/home/eprints-3.4.3/</Code>) then no change is required. If ~~it is~~ not present in the latest version you need to consider whether it can/should be copied across (e.g. into <Code>/home/eprints/eprints-3.4.3/flavours/pub_lib/inc</Code>). It is likely new ingredients will be added to a flavours inc file between versions, so this file is particular important to check so your repository's local modifications to this file and modifications in the latest version of EPrints can be reconciled.		If the files in <Code>/opt/eprints3/</Code> are the same as that in the latest version (e.g. <Code>/home/eprints-3.4.3/</Code>) then no change is required. If some are not present in the latest version you need to consider whether they can/should be copied across (e.g. into <Code>/home/eprints/eprints-3.4.3/flavours/pub_lib/inc</Code>). It is likely new ingredients will be added to a flavours inc file between versions, so this file is particular important to check so your repository's local modifications to this file and modifications in the latest version of EPrints can be reconciled.

	4. If your repository has any Bazaar plug-ins installed go to the Eprints Bazaar page on your repository via the Admin menu and download each one individually from the ''Developer Tools'' tab.		4. If your repository has any Bazaar plug-ins installed go to the Eprints Bazaar page on your repository via the Admin menu and download each one individually from the ''Developer Tools'' tab.
Line 51:		Line 51:
	If <Code>/opt/eprints3/archives</Code> or any of its archives are on a different disk partition, this may take a long time and the partition you are moving it to may not be big enough. It may be better to figure out an alternative way of updating the other EPrints directories without moving the archive between disk partitions and then switching round the eprints directories (step 9 below).		If <Code>/opt/eprints3/archives</Code> or any of its archives are on a different disk partition, this may take a long time and the partition you are moving it to may not be big enough. It may be better to figure out an alternative way of updating the other EPrints directories without moving the archive between disk partitions and then switching round the eprints directories (step 9 below).

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

Line 180:		Line 180:
	apachectl start		apachectl start
	/opt/eprints3/bin/indexer start		/opt/eprints3/bin/indexer start

	~~=== From Linux package repository ===~~
	~~'''New versions of EPrints 3.4 will not longer be released as Linux packages (i.e. RPMs or debs).'''~~

Drn@ecs.soton.ac.uk: /* From Linux package repository */

2025-02-16T22:56:27Z

From Linux package repository

← Older revision		Revision as of 22:56, 16 February 2025
Line 182:		Line 182:

	=== From Linux package repository ===		=== From Linux package repository ===
	'''N.B. ~~These instructions are a work in progress~~.'''		'''New versions of EPrints 3.4 will not longer be released as Linux packages (i.e. RPMs or debs).'''

Drn@ecs.soton.ac.uk: /* Clean Upgrade */

2023-05-03T10:14:30Z

Clean Upgrade

← Older revision		Revision as of 10:14, 3 May 2023
Line 137:		Line 137:

	==== Clean Upgrade ====		==== Clean Upgrade ====
	Step 1 needs to be done as the root. Steps 2 and onwards ~~need to~~ 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.

	1. Create a new directory for latest version of eprints (substituting X for the latest version):		1. Create a new directory for latest version of eprints (substituting X for the latest version):

Drn@ecs.soton.ac.uk: /* In-place Upgrade */

2023-05-03T10:14:12Z

In-place Upgrade

← Older revision		Revision as of 10:14, 3 May 2023
Line 107:		Line 107:

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

	1. Stop the webserver and EPrints indexer.		1. Stop the webserver and EPrints indexer.
	apachectl graceful-stop		apachectl graceful-stop

Drn@ecs.soton.ac.uk: /* Clean Upgrade */

2023-05-03T10:13:20Z

Clean Upgrade

← Older revision		Revision as of 10:13, 3 May 2023
Line 135:		Line 135:

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

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

Drn@ecs.soton.ac.uk: /* Clean Upgrade */ Improved clone and checkout advice

2023-05-03T10:07:56Z

Clean Upgrade: Improved clone and checkout advice

← Older revision		Revision as of 10:07, 3 May 2023
Line 141:		Line 141:

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

Th.lauke@arcor.de: graceful-stop introduced & some typos removed

2023-01-06T14:50:41Z

graceful-stop introduced & some typos removed

Th.lauke@arcor.de: graceful-stop & inc move back introduced

2023-01-06T14:37:32Z

graceful-stop & inc move back introduced

← Older revision		Revision as of 14:37, 6 January 2023
Line 108:		Line 108:
	==== In-place Upgrade ====		==== In-place Upgrade ====
	1. Stop the webserver and EPrints indexer.		1. Stop the webserver and EPrints indexer.
	apachectl stop		apachectl graceful-stop
	/opt/eprints3/bin/indexer stop		/opt/eprints3/bin/indexer stop

Line 118:		Line 118:
	git checkout v3.4.X		git checkout v3.4.X

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

	5. Test the new configuration and fix ans issues reported.		5. Test the new configuration and fix ans issues reported.

Th.lauke@arcor.de: typos and useless commands removed

2022-12-29T12:05:41Z

typos and useless commands removed

← Older revision		Revision as of 12:05, 29 December 2022
Line 98:		Line 98:
	The only file that should have been modified (assuming you are running a publications flavour of EPrints) is ''flavours/pub_lib/inc''.		The only file that should have been modified (assuming you are running a publications flavour of EPrints) is ''flavours/pub_lib/inc''.

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

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

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

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

	==== In-place Upgrade ====		==== In-place Upgrade ====
Line 114:		Line 114:
	cp /opt/eprints3/flavours/FLAVOUR_lib/inc /home/eprints/inc.backup		cp /opt/eprints3/flavours/FLAVOUR_lib/inc /home/eprints/inc.backup

	3.This can be done with the following commands (substituting X for the latest version):		3. Get the latest code version. This can be done with the following commands (substituting X for the latest version):
	git fetch		git fetch
	git checkout v3.4.X		git checkout v3.4.X
Line 122:		Line 122:
	/opt/eprints3/flavours/FLAVOUR_lib/inc		/opt/eprints3/flavours/FLAVOUR_lib/inc

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

Line 133:		Line 133:
	8. Start the webserver and EPrints Indexer		8. Start the webserver and EPrints Indexer
	apachectl start		apachectl start
	/opt/eprints3/bin/indexer ~~stop~~		/opt/eprints3/bin/indexer start

	==== Clean Upgrade ====		==== Clean Upgrade ====
Line 162:		Line 162:
	mv /opt/eprints3 /opt/eprints3.old		mv /opt/eprints3 /opt/eprints3.old
	mv /opt/eprints3.4.X /opt/eprints3		mv /opt/eprints3.4.X /opt/eprints3
	~~mkdir /opt/eprints3/archives/~~
	mv /opt/eprints3.old/archives/ARCHIVEID /opt/eprints3/archives/		mv /opt/eprints3.old/archives/ARCHIVEID /opt/eprints3/archives/

Line 176:		Line 175:
	11. Start the webserver and EPrints Indexer		11. Start the webserver and EPrints Indexer
	apachectl start		apachectl start
	/opt/eprints3/bin/indexer ~~stop~~		/opt/eprints3/bin/indexer start

	=== From Linux package repository ===		=== From Linux package repository ===
	'''N.B. These instructions are a work in progress.'''		'''N.B. These instructions are a work in progress.'''

← Older revision		Revision as of 14:50, 6 January 2023
Line 141:		Line 141:

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

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

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

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

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

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

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

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