OED Documentation

Upgrades

Version V0.7.0

The latest version of this page is V1.0.0.

Documentation overview

Admin documentation
Information
User documentation
Documentation versions for this page
V1.0.0
V0.8.0
V0.7.0 (current page)

These features are only available to select people who oversee the OED site (called admins) so this information is not usually of interest to a general user.

To upgrade the app:

  1. The commands are run in the terminal and it assumes you understand basics of installing OED. See the OED installation page for further information.
  2. You probably want to know your current version of OED and the version you want to upgrade to. The current version of OED is shown at the bottom of each OED website page from your site. Simply go to the URL for your site and see what version you have. If you are running v0.6.0 or earlier then the OED version is not on the website pages. Then, the OED version is also listed in the package.json file in the root directory of OED. All the officially released and tagged versions is given on the OED GitHub release page. You probably want the most recent version but certainly one that is later than what you currently have (OED cannot migrate to a previous version and can only upgrade).
  3. Go to the root directory where you have OED installed. It will have the README.md and other files.
  4. The following steps should not cause any loss of data. However, it is always good to be careful. Thus, you should backup the database with: docker compose exec database pg_dump -U oed > dump_$(date +%Y-%m-%d"_"%H_%M_%S.sql). It will create a file name starting with dump_, then have the date & time and finally have the .sql file extension. This file should have the needed commands to recreate the database if something should go wrong. You can delete this file once you are sure the upgrade was completely successful if you want to save disk space. You can contact the OED project if you need to restore the database due to issues.
  5. Stop the OED app from running using: systemctl stop oed.service. This assumes you named the service oed.service as is the default in the installation directions. You can check the status of the service with systemctl list-units --type=service | grep -i oed where it will not be listed if it is stopped. Note this means that the OED website/service is no longer available. It will not be permanently available again until you restart the OED service at the end of this process.
  6. Store your local config changes with: git stash
  7. Make sure you have the latest git information on the tagged version that were created after your last installation with: git fetch --tags.
  8. Update the code to the desired tagged version with: git checkout <tag_name> where you replace <tag_name> with the tagged version you want. For example, to go to v0.7.0 use git checkout v0.7.0.
  9. Put back your local changes with: git stash pop. You will see messages including about Changes not staged for commit:. This is okay since you are not going to commit these changes back to the OED repository (you are actually in a detached head git state). It is unlikely that git cannot put back your local changes. If you get merge warnings then see if the named file has lines with multiple "<<<<" and ">>>>" in a row. If so, then there were merge conflicts. You can try to edit the file to decide which of the listed lines you need. You are also encouraged to contact the OED project for help with this situation.
  10. You now need to upgrade the OED system with: docker compose run --rm web src/scripts/updateOED.sh. This will reinstall the node packages because there are usually changes, update the database for the new version of OED and then build the new application. When you see a line similar to [at-loader] Using typescript@3.5.3 from typescript and "tsconfig.json" from /usr/src/app/tsconfig.json. in the terminal, OED will be doing the install and may take a while to complete without showing any output.
  11. Though not technically necessary, it isn't a bad idea to manually bring up OED with: docker compose up. This is the same step as the original build from the first OED installation and can take a little while. See the OED installation page for further information. You should then be able to access OED via a web browser to see it is running properly and has all the data and settings you had before the upgrade. Doing it outside the Unix service makes it easier to see any issues during the build steps. Once you complete this step then do "^c" in the terminal where you did the docker compose up to shut down OED. Be a little patient since doing a second "^c" will cause a rapid stop of docker without the normal cleanup.
  12. Restart the OED app and service with: systemctl start oed.service.