Eidetic Installation

1. Software

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

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

Make sure you have a global cgi-bin directory, such as /var/www/cgi-bin. This typically is already set up for you, but if not, here is an example Apache config snippet:

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

make install_repository

THIS WILL DESTROY any currently installed document repository.

4. 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);"

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

RPM

If you use RPM to maintain your packages, here is the command to create an RPM of Eidetic:

$ perl Makefile.PL
$ make
$ make test
$ make dist
$ su
# rpmbuild -ta Eidetic-VERSION.tar.gz

You may want to alter the version tag in lib/Eidetic.pm and in the META.yml file.

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.