Installation

Requirements

SeedDMS is a web-based application written in PHP. It uses MySQL, SQLite3 or PostgreSQL to manage the documents that were uploaded into the application. Be aware that PostgreSQL is not very well tested.

Make sure you have PHP >= 7.2 and MySQL 5 or higher installed. SeedDMS will work with PHP running in CGI-mode as well as running as a module under apache.

Here is a detailed list of requirements:

  1. A web server with at least php 7.2

  2. A mysql database, unless you use SQLite

  3. The php installation must have support for pdo_mysql, pdo_pgsql or pdo_sqlite, php_gd2, php_mbstring, php_xml

  4. Depending on the configuration the extensions php_ldap, php_mycrypt, php_gmp, php_libsodium must be installed

  5. Various command line programms to convert files into text for indexing pdftotext, catdoc, xls2csv or scconvert, cat, id3 (optional, only needed for fulltext search)

  6. ImageMagic (the convert program) is needed for creating preview images

  7. A bunch of packages from Packagist which all ship with the seeddms-quickstart archive

It is highly recommended to use the quickstart archive (seeddms-quickstart-x.y.z.tar.gz) because it includes all software packages (excluding those listing above in item 1. to 6.) for running SeedDMS. Hence, you still need a working web server with PHP and in addition a MySQL or PostgreSQL database unless you intend to use SQLite.

Choosing the right database

SeedDMS supports the following databases

  • SQLite3

  • msyql

  • postgresql (not well tested)

For smaller installations it is mostly a matter of taste which database you use. For larger installations with > 10000 documents and many concurrent users (> 10) it is worthwhile to use mysql in all other case sqlite3 is sufficient. sqlite3 is easily set up and backups of the data directory already include all the data required for a new installation after a data loss.

Switching from one database to another after documents have been uploaded is possible but may require some profound knowlegde on databases and considerable effort.

Choosing the right collation

Mysql offers various character sets and collations for a database. The character set and the collations has impact on

  • the characters which can be saved in text fields

  • how sorting by a text field is done

  • how string operations work

While years ago ‘latin1’ was quite often used, nowadays ‘utf8mb4’ is the preferred character set, because it can handle all characters defined by utf8 (even emojis).

A character set has a default collation but you may as well change it on a database, table or field level. SeedDMS uses the collation ‘utf8mb4_unicode_ci’ by default. Hence you should create your database like

CREATE DATABASE seeddms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

‘utf8mb4_unicode_ci’ is a case insensitive collation which means that searching for ‘test’ will also return occurences of ‘Test’ or ‘tESt’. For a case insensitive search ‘utf8mb4_bin’ should be used.

Whether you use ‘utf8mb4_unicode_ci’ or ‘utf8mb4_bin’ has major impact on all search operations in SeedDMS. This is especially true when documents or folders are searched by its name. The WebDAV interface heavily depends on filenames and its uniqueness. It uses the document and folder name by default. As SeedDMS does not necessarilly keep you from creating two documents which only differ by case, one document may cover the other one when accessing it through WebDAV. Only the first one found will be visible. Uploading a file with a name which only differs in case will update an existing document.

Installing the software

SeedDMS is shipped as a tar archive named seeddms-quickstart-a.b.c.tar.gz. In unpacks into a directory seeddmsABx (with A and B being the major and minor version number). Let’s assume you use seeddms-quickstart-5.1.23.tar.gz. It will create a new directory seeddms51x containing everything you need to run SeedDMS with SQLite3. Even if you intend to use mysql in the long run it is advisable to first set up SeedDMS with SQLite3 and than just switch the database.

Setting up the web server

First of all you will need to set up your web server. Here, we will only focus on apache running on Debian/GNU Linux. Either let the document root of your web server point to the directory www below seeddms51x

DocumentRoot /var/www/seeddms51x/www

or add an alias. For apache this could be like

Alias /seeddms51x /<some directory>/seeddms51x/www

or even

Alias /mydms /<some directory>/seeddms51x/www

Do not set the DocumentRoot or Alias to the seeddms51x directory, because this will allow anybody to access your data and conf directory if it is not secured by a .htaccess file. This is a major security risk.

Make sure that the subdirectory seeddms51x/data and the configuration file seeddms51/conf/settings.xml is writeable by your web server. All other directories can be just readable by your web server, though it is advisable to even protect them from writing.

Adjusting the configuration of SeedDMS

In the next step you need to adjust the configuration file in seeddms51x/conf/settings.xml. Open the file in your favorite text editor and search for /home/wwww-data. Replace that part in any path found with your base directory where you placed seeddms51x (e.g. /var/www/html/seeddms51x). Alternatively, you can open the installer with a browser at http://your-domain/install (if the document root points to seeddms51x/www) or http://your-domain/seeddms51x/install/ (if you have set an alias like described above).

It will first ask to unlock the installer by creating a file ENABLE_INSTALL_TOOL in the diretory seeddms51x/conf/. Change all paths by replacing /home/www-data with your base directory where you put seeddms51x. Set httpRoot to / (if the document root points to seeddms51x/www) or /seeddms51x (if you have set an alias seeddms51x like described above).

Once your configuration is done, save it, remove the file ENABLE_INSTALL_TOOL and point your browser to http://your-domain/ or http://your-domain/seeddms51x.

Security considerations

You should always access your SeedDMS installation through a secured https connection, unless you precisly know what you are doing. SeedDMS ships an .htaccess file which already has some common security http headers set. In order for them to apply you need to activate the headers module. On Debian/GNU Linux this can be done with

a2enmod headers

Protect directories with data or configuration

A crucial point when setting up SeedDMS is the propper placement of the data directory. Do not place it below your document root of your web server! If you do so, there is a potential way that attackers can easily access your documents with a regular web browser. If you cannot place the data directory outside of document root, then either restrict access to it with an appropriate .htaccess file like the following. The SeedDMS quickstart archive already includes this .htaccess file.

# line below if for Apache 2.4
<ifModule mod_authz_core.c>
Require all denied
</ifModule>

# line below if for Apache 2.2
<ifModule !mod_authz_core.c>
deny from all
Satisfy All
</ifModule>

# section for Apache 2.2 and 2.4
<ifModule mod_autoindex.c>
IndexIgnore *
</ifModule>

Alternatively or in addition you can change the contentOffsetDir in settings.xml to something random, but ensure it is still a valid directory name. If you change contentOffsetDir, then do not forget to move data/1048576 to data/<your random name>. Also turn off directory listings in your apache configuration for the data directory.

Securing the configuration file

The configuration can be fully controlled by any administrator of SeedDMS. This can be crucial for those configuration options where external commands are being configured, e.g. for the full text engine or creating preview images. As a hoster you may not want this configuration options being set by a SeedDMS administrator. For now you need to make the configuration file settings.xml unwritable for the web server. In that case the SeedDMS administrator can still see the configuration but will not be able to change it.

Since version 5.1.23 and 6.0.16 of SeedDMS there is some preliminary way to hide parts of the configuration which makes them unchangeable for the SeedDMS administrator.

Setting a new encryption key

Though this is not related to setting up the web server environment, it is important to recreated the encryption key in SeedDMS once SeedDMS is running. Just open the settings in the admin tools and empty the currently set encryption key on the tab ‘System’. Save the settings and check the key again. It should be a new one. Save the settings again. The encryption key is mainly used for creating tokens in HTML forms to prevent CSRF attacks.

Upgrading from a previous version of SeedDMS

As SeedDMS is a smooth continuation of LetoDMS there is no difference in updating from LetoDMS or SeedDMS.

You have basically two choices to update SeedDMS:

  • you install a fresh version of SeedDMS and copy over your data and configuration

  • you replace the software in your current installation with a new version

The first option is less interuptive but requires to be able to set up a second temporary SeedDMS installation, which may not be possible, e.g. because of storage limitations. It can be the only option if you change servers.

The first update procedure is only needed if the version changes on the minor or major version number. Changes in the subminor version number will never include database changes and consequently it is sufficient to use the existing data directory and database with the new version. Choose the second update option in this case.

In both cases make sure to have a backup of your data directory, configuration and database.

Fresh installation and take over of data

The first update option is to set up a new instance of SeedDMS and once that is running take over the data from your current (old) instance.

  1. just do a fresh installation somewhere on your web server and make sure it works. It is fine to use SQLite for it, even if your final installation uses MySQL.

  2. replace the data directory in your new installation with the data directory from your current installation. Depending on the size of that directory (and whether the new installation is on a new server or the old server) you may either copy, move or place a symbolic link. The content of the data directory will not be changed during the update. Its even perfectly save to browse through your documents and download them after finishing the update. The data directory will not be modified until you actually modify documents.

  3. copy over the configuration settings.xml into your new installation. This will effectively make your new installation use the data from your old installation, because all paths are still pointing to the old installation.

  4. if you use mysql you could as well make a copy of the database to make sure your current database remains unchanged.

  5. modify the settings.xml to fit the environment of the new installation. This will mostly be the httpRoot, the paths to the installation directory and possibly the database connection.

  6. create a file ENABLE_INSTALL_TOOL in the conf directory and point your browser at http://hostname/seeddms/install The install tool will detect the version of your current SeedDMS installation and run the required database updates. If you update just within the last version number (e.g. from 5.1.6 to 5.1.9), this step will not be required because such a subminor version update will never contain database updates.

Upgrading your current installation

Instead of setting up a new installation, you may as well replace the php files in your current installation with new versions from the quickstart archive.

  1. get the SeedDMS quickstart archive seeddms-quickstart-x.y.z.tar.gz and unpack it somewhere on your disc.

  2. copy the directory seeddms-x.y.z from the unpacked archive into your current installation and make the link seeddms point to this new directory.

  3. copy the directory pear from the unpacked archive into your current installation, replacing the existing directory. Make a backup of pear before the replacement if you want to ensure to be able to go back to your old version.

  4. you may compare your conf/settings.xml file with the shipped version conf/settings.xml.template for new parameters. If you don’t do it, the next time you save the configuration the default values will be used.

  5. create a file ENABLE_INSTALL_TOOL in the conf directory and point your browser at http://hostname/seeddms/install The install tool will detect the version of your current SeedDMS installation and run the required database updates. If you update just within the last version number (e.g. from 5.1.6 to 5.1.9), this step will not be required because such a subminor version update will never contain database updates.