Editing Upgrading (section)

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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