Eidetic Document Management System
Docsys Installation
0. Pre-requisites
For a list of pre-requisites, see the PREREQ_PM section of Makefile.PL. The versions listed are ones that have been tested; earlier versions may also work.
For Authentication/Authorization (optional), you'll need the following:
- Apache-AuthCookie-2.011 or later
- Apache-AuthTicket-0.31 or later
It may be possible to tie DocSys into other authentication systems, but only the above system has been tested. If you do get DocSys working with another system, please post a patch to the DocSys Sourceforge project page.
1. Software Installation
To install the script and man pages in the standard areas, give the sequence of commands
perl Makefile.PL
make
make test
make install # you probably need to do this step as superuser
If you want to install the script in your own private space, use
perl Makefile.PL PREFIX=/home/joeuser
INSTALLMAN1DIR=/home/joeuser/man/man1
INSTALLMAN3DIR=/home/joeuser/man/man3
make
make test
make install # can do this step as joeuser
Installation includes not only binary and library files but also templates, config files, etc. Be aware that this could overwrite customizations you've made to these files.
Makefile.PL installs files to various locations. You can override these locations by passing cmdline args to Makefile.PL, as follows, with defaults as indicated:
httpd_dir='/etc/httpd/conf',
dms_dir='/var/dms',
cgi_dir='/var/www/docsys/cgi-bin',
img_dir='/var/www/docsys/images',web_user='apache',
web_group='apache',
Be aware that you'll need to use these same settings in the Configuration step, below.
You also need to create a directory for docsys to post documents to, and ensure apache has write access to that directory. For example:
Easy way (assuming you have DocumentRoot set to /var/www/html):
# mkdir /var/www/html/docs
# chown www:www /var/www/html/docs
# chmod 0755 /var/www/html/docs
Better way (segregate it from your main DocumentRoot):
# mkdir /var/www/docsys/docs
# chown www:www /var/www/docsys/docs
# chmod 0755 /var/www/docsys/docs
You'll also need to create an Alias and
2. Database
Be sure to backup your database before dropping and reinstalling it, else all your data will be lost.
The installation scripts assume that the root user has full access to mysql; if not, you should set up your .my.sql or the global my.sql config file to permit this (or alter the sql install files to suit your environment).
To install the database, issue this command as superuser:
make install_mysql_db
This command runs the load_db.sh script located in the sql/ directory. (Essentially, it simply does `cat *.sql | mysql`.)
THIS WILL DESTROY any existing docsys database!
You will need to set up a database user for your database. The sample config file uses user/password user/"pass", but you should change it to something better. Here's one way to do this (as root):
# mysqlaccess localhost user docsys --commit
You will also need to set up a website user to be able to access the system from the web. By default, `make install_mysql_db` creates a user/pass as test/test (uid#999); you'll want to drop this user from the database when you deploy for production use (or at least change the password). See Configuration, below. If you're integrating this application into an existing authentication environment, you're on your own.
3. Apache
Refer to Apache::AuthTicket / Apache::AuthCookie installation directions, if you wish to use that system for authentication. You can obtain and install RPM's of each of these, or install from CPAN, or whatever. For configuring Apache to use AuthTicket, either refer to its documentation, or see below.
Here is an example Apache config snippet to set up the docsys cgi-bin directory:
AllowOverride All
Options ExecCGI
Order allow,deny
Allow from all
You will need to restart apache after making any changes to config files, in order for the changes to take effect.
You will also require an authenticated area. The purpose of this is to establish a privileged area through which docsys transactions (changing metadata, revising docs, etc.) can occur. Here's an example config snippet, useful for testing the system:
Options ExecCGI
Order deny,allow
Deny from all
Allow from 127.0.0.1
#allow from .your_domain.com
This allows you to access the advanced functions via localhost. Note that since you're not logging in, the software won't know what username to use, and will error, so is useful only for troubleshooting during initial installation, or if you intend to use an authentication system other than AuthTicket and simply want to validate basic functionality.
If you are using AuthTicket, you will need to configure Apache to make use of it. See httpd/authticket.conf and make whatever changes you wish. `make install` will copy it to /etc/httpd/conf (or ${PREFIX}/etc/httpd/conf). To hook it up, you will need to add a line such as the following, to your httpd.conf:
Include conf/commonhttpd.conf
4. Document Repository
To install the document repository, run as superuser:
make install_repository
THIS WILL DESTROY any currently installed document repository.
5. Configuration
Set the configuration variables for the software to match the choices you've made regarding names of databases, file locations, etc.
Don't forget to save a backup of your configuration settings. When you run `make install`, it will overwrite any custom settings made in the global config file.
A default user account is automatically set up during installation, with the username and password 'test' and 'test'. This is set up as user id number 999. You can safely delete this user once you are certain the system is installed, configured, and working correctly. The password is encrypted using Digest::MD5; depending on how you set up your authentication scheme, this may or may not be suitable for you. For reference, the following command is what produces the default password.
perl -e use Digest::MD5(md5_hex); print md5_hex('test'), qq(\n);
6. Backup
In addition to the configuration settings, the two things you will want to include in your backup process are the document repository and the database.
You may want to shut down the document management system during the backup process, if you are concerned about transactions occurring during the backup process. Temporarily shutting down Apache and MySQL will accomplish this.
The document repository is a regular file system, so back it up as you would any other file system data.
To backup the database, use the particular database's normal backup processes. For instance, for mysql, use `mysqldump`. See mysqldump's man page for more info.
Restoring from a backup is simply a reverse of the above: Install the database dump into the db, restore the DMS file system, and ensure the configuration parameters are consistent with how they were at time of backup.
7. Thumbnail Creator Delegates
Optionally, you may wish to install some delegates for Image::Magick that will allow it to produce thumbnails of a wider variety of document types. By default, Image::Magick includes built-in support for a number of image formats. Using some commonly available tools/libraries such as ghostscript, libpng, etc. it is able to cover a number of different kinds of documents. You may need to install some less common tools for common formats to get full coverage of your needs, such as:
- html2ps - for thumbnailing HTML documents
- libxml - for SVG, etc.
For complete info on delegate applications, please refer to the ImageMagick documentation on file formats:
One cause of problems with the thumbnail generation is font installation path discrepancies. For instance, if ghostscript's fonts are missing, this will cause issues with many thumbnail operations (including processing the output of html2ps). It can be useful to try running `ghostscript` on the documents that are exhibiting issues, to get useful error messages. Ghostscript fonts can be found here:
ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/AFPL/fonts/
Not all SVG documents will thumbnail properly. For example, Sodipodi-generated SVG documents will lose gradients, etc.
RPM
If you use RPM to maintain your packages, here is the command to create an RPM of DocSys:
$ perl Makefile.PL
$ make
$ make test
$ make dist
$ su
# rpmbuild -ta docsys-VERSION.tar.gz
You may want to alter the version tag in Makefile.PL, docsys.spec, and in the META.yml file.
This will result in the creation of SRPM and RPM files under /usr/src/redhat/, or whereever your system is configured to place packages.
Uninstallation
Under a user with sufficient permissions and from the program distribution directory, execute
perl Makefile.PL
if there isn't a file called Makefile. Then execute
make uninstall
This sometimes works, and sometimes it does not. If it refuses to work, you can simply remove all files by hand. Look for the .packlist file which perl created when installing the software and remove all files you find in there.
If you've installed using rpm, uninstallation works using the usual rpm processes.