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 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

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:



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 section in your Apache config - see the httpd/ dir in this distribution for examples.

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 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:

AllowOverride None
Options ExecCGI
Order deny,allow
Deny from all
Allow from

#allow from

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:

Not all SVG documents will thumbnail properly. For example, Sodipodi-generated SVG documents will lose gradients, etc.


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.


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.

Brought to you by the Open Source Development Labs