From 567488cab96e7bc6ed13f5fc8660cea4199e1a6b Mon Sep 17 00:00:00 2001 From: Uwe Steinmann Date: Fri, 27 Aug 2021 09:55:58 +0200 Subject: [PATCH] lots or minor corrections and updates --- doc/README.Install.md | 170 +++++++++++++++++++++++++----------------- 1 file changed, 100 insertions(+), 70 deletions(-) diff --git a/doc/README.Install.md b/doc/README.Install.md index e18de00b2..89c317942 100644 --- a/doc/README.Install.md +++ b/doc/README.Install.md @@ -5,8 +5,8 @@ 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. +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 @@ -15,11 +15,11 @@ 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 +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 + `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) @@ -30,7 +30,8 @@ Here is a detailed list of requirements: 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 postgres database unless you intend to use sqlite. +you still need a working web server with PHP and in addition a mysql or +PostgreSQL database unless you intend to use SQLite. QUICKSTART =========== @@ -39,8 +40,8 @@ The fastes way to get SeedDMS running is by unpacking the archive `seeddms-quickstart-x.y.z.tar.gz` on your webserver. Let's assume you use seeddms-quickstart-5.1.x.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 +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 @@ -86,8 +87,8 @@ 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). +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 @@ -97,10 +98,10 @@ SECURITY CONSIDERATIONS ======================= You should always access your SeedDMS installation through -a secured https connection, unless you know precisly what are you doing. +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 this can be done with +headers module. On Debian/GNU Linux this can be done with ``` a2enmod headers @@ -110,19 +111,13 @@ 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 as -configured in your web server! If you do so, there is a good change that +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, than either -restrict access to it with an appropriate .htaccess file or/and 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/`. -Also turn off directory listings in your apache configuration for the -`data` directory. +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. -Example for .htaccess file in data directory ----------------------------------------------- ``` # line below if for Apache 2.4 @@ -141,6 +136,14 @@ IndexIgnore * ``` +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/`. +Also turn off directory listings in your apache configuration for the +`data` directory. + + Securing the configuration file --------------------------------- @@ -152,27 +155,40 @@ 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 new one. Save the settings 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. -UPGRATING FROM A PREVIOUS VERSION OR SEEDDMS +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 +in updating from LetoDMS or SeedDMS. -You have basically two choices to update 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. +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. @@ -180,56 +196,70 @@ and database. Fresh installation and take over of data ----------------------------------------- -- 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. -- replace the data directory in your new installation with the data directory - from your current installation. Depending on the size of that directory you - may either copy, move or place a symbolic link. The content of the data directory - will not be changed unless you modify your documents. Its perfectly save to - browse through your documents and download them. -- copy over the configuration settings.xml into your new installation -- if you use mysql you could as well make a copy of the database to make sure - your current database remains unchanged. As long as you do not do any modification, - you could even use your current database. -- modify the settings.xml to fit the fresh install. This will mostly be the - httpRoot, the paths to the installation directory and possibly the database - connection. -- 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. -- test your new installation. +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 ----------------------------------- -- make a backup of your data folder and the configuration file settings.xml -- in case you use mysql then dump your current database -- get the SeedDMS archive seeddms-x.y.z.tar.gz and all pear packages - SeedDMS_Core, SeedDMS_Lucene, SeedDMS_Preview and extract them over your - current instalation. As they do not contain a data directory nor a settings.xml - file, you will not overwrite your existing data and configuration. -- 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. -- 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. +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. THE LONG STORY ================ +This section is mostly outdated but may still contain some valueable +information for those trying to understand the installation process. + If you intend to run a single instance of SeedDMS, you are most likely better off by using the quickstart archive as described above. This section is mostly for users who wants to know more about the internals @@ -315,7 +345,7 @@ http://localhost/seeddms/ * Point you web browser towards http://hostname/seeddms/install/ * Follow the instructions on the page and create a file `ENABLE_INSTALL_TOOL` - in the conf directory. + in the `conf` directory. * Create a data directory with the thre sub directories staging, cache and lucene. @@ -424,7 +454,7 @@ If you install SeedDMS for the first time continue with the database setup. e.g. for mysql: > cat create_tables-innodb.sql | mysql -useeddms -p seeddms This step can also be done by the install tool. -* create a file `ENABLE_INSTALL_TOOL` in the conf directory and point +* create a file `ENABLE_INSTALL_TOOL` in the `conf` directory and point your browser at http://hostname/seeddms/install