Upgrades

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. If you are upgrading from before OED v1.0.0 to v1.0.0 or higher, then you need to special steps for upgrading the database. This is a one-time process and not needed unless you are doing this migration. Once you complete those step you return here to continue a standard migration.
6. 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.
7. Store your local config changes with: git stash
8. Make sure you have the latest git information on the tagged version that were created after your last installation with: git fetch --tags.
9. 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.
10. 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.
11. 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. At the start you will see "NPM ci to upgrade the packages..." and this can take a while to complete. Next you should see "NPM install finished." followed by "Attempting to migrate database to latest version...". Finally it will do "Doing docker compose up --no-start --build to capture any changes needed for images/containers without starting...". If all does well you will see "webpack 5.67.0 compiled successfully" followed by "OED upgrade completed".

    Certain upgrade are failing for unknown reasons upgrade. If this happens, do the following:

    • Delete the node_modules/ directory
    • Remove the docker containers associated with OED. First, find them with docker container ls -a. You don't want to accidentally remove another docker container. There should be one with oed_web and one oed_database (or similar names). The OED containers should not be currently running so they should have "Exited" as the "STATUS". The first column listed should be "CONTAINER ID". For each CONTAINER ID, do: docker container rm <CONTAINER ID>. The response should be an echo of the <CONTAiNER ID>. If you list the containers again these should be gone. At this point you should be able If you have any issues or questions then please don't hesitate to reach out to the project.
12. It is a good idea to make sure OED is working properly before you restart the service. This can be accomplished by doing: docker compose up. This is the same step as the original build from the first OED installation but will likely happen faster since the OED software was updated above. See the OED installation page for further information. Once complete, 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.
13. Restart the OED app and service with: systemctl start oed.service.