The quick way to update a SeedDMS installation

SeedDMS comes with rather detailed instructions on how to install and update the software. It’s all described in the file doc/README.Install.md which is part of the quickstart archive. This article focuses on a very special but quite regular case, when SeedDMS is updated without changing the major and minor version number. Hence, all updates within the SeedDMS 5.1.x or 6.0.x series, e.g. from 6.0.22 to 6.0.28.

SeedDMS’ folder structure on disk is designed to be secure and easily updateable. The parts to be replaced during an update are located in two directories in the base directory named pear and seeddms-5.1.x or seeddms-6.0.x. All other directories remain unchanged. This is achieved by soft links within the directory www and it enforced to run SeedDMS on a platform supporting soft links. If this in not the case, this article may still be useful to understand the update process but you will have to dereference the links yourself.

The basic idea is that the directory www (which should be your document root) doesn’t have version depended links. It only contains links to ../seeddms/xxx. ../seeddms itself is not a directory but also a link to seeddms-5.1.x or seeddms-6.0.x (with x being the subminor version number of your installation). In case of an update all you need to do is let seeddms point to a new seeddms-5.1.y or seeddms-6.0.y which you have copied into the base directory from the latest quickstart archive (with y being the subminor version of the new SeedDMS).

In some cases this is already sufficient, but to be sure to have all latest changes, you should also update the pear directory. It doesn’t have a version number in its name, so you need to replace the whole directory with the new version from the quickstart archive. Well, actually I quite often establish the same link structure for the directory pear as for seeddms when doing the first update. That facilates further updates. E.g. for updating from 6.0.22 to 6.0.28 with the unpacked quickstart archive in /tmp

mv pear pear-6.0.22
cp -a /tmp/seeddms60x/pear .
mv pear pear-6.0.28
ln -s pear-6.0.22 pear
cp -a /tmp/seeddms60x/seeddms-6.0.28 .

Hence, your seeddms base directory should look like

seeddms-base-dr
├── conf
├── data
├── pear -> pear-6.0.22
├── pear-6.0.22
├── pear-6.0.28
├── seeddms -> seeddms-6.0.22
├── seeddms-6.0.22
├── seeddms-6.0.28
└── www

Now, switching to the new version is a simple as

rm seeddms; ln -s seeddms-6.0.28 seeddms
rm pear; ln -s pear-6.0.28 pear

but going back is just as simple (in case something is not working)

rm seeddms; ln -s seeddms-6.0.22 seeddms
rm pear; ln -s pear-6.0.22 pear

After switching between versions you may have to restart your web server and/or php-fpm (if you use that) to ensure the cache is cleared. It may also be necessary to clear your browser cache.

This already makes updates almost risk free, but there is another thing which you may have to consider if you are using extensions. Extensions installed in a older version may not work anymore with a new version of SeedDMS. Often it is sufficient to update the extensions before updating SeedDMS, but sometimes new extension do not work with older SeedDMS versions and vise versa. You basically end up with two different sets of extensions (meaning different versions). To fix this update problem just apply the same trick as for seeddmѕ and pear. First make a copy of your current extensions into a new extension directory containing the version number and rename the existing directory.

cd www
mv ext ext-6.0.22
ln -s ext-6.0.22 ext
cp  ext-6.0.22 6.0.28

If you have already switched your SeedDMS installation to the new version, run

rm ext; ln -s ext-6.0.28 ext

The extensions are still identical to those in your old version, because ext-6.0.28 is a copy of ext-6.0.22. Open the extension manager in your web browser and update the extensions. Since ext is pointing to ext-6.0.28, your old extensions in ext-6.0.22 will not be touched and you can easily go back to your old version of SeedDMS. During update of the extensions you will probably warn your users or even make your SeedDMS inaccessible for regular users.

After updating …

It is usually good pratice to rebuild the full text index after you have updated your SeedDMS installation, because the schema of the index changes once in while.

What if a major or minor version number changes?

I wrote at the very beginning of this article, this simplified update procedure can only be applied on changes of the subminor version. The reason is that bigger version changes also include database changes and those changes cannot easily be undo unless you make a backup of your database. Anyway, if you are an experienced sys admin, you could use this article as a blueprint and even update greater version changes.

Conclusion

Setting up soft links to your current and new version of SeedDMS allows to switch between two (or more) versions without running the risk of a longer downtime due to update problems.