seeddms-code/trunk

-------------------------------------------------------------------
              LetoDMS Installation Instructions
-------------------------------------------------------------------

IMPORTANT NOTE ABOUT TRANSLATIONS ==============================================

as you can see letoDMS provide a lot of languages but we are not professional 
translators then we wait for users contributions.

If your language is not present in the login panel:
- copy the language/english/ folder and rename it appropriately for your
  language
- open the file languages/your_lang/lang.inc and translate it
- open the help file languages/your_lang/help.htm and translate it too

If you see some wrong or not translated messages:
- open the file languages/your_lang/lang.inc
- search the wrong messages and translate them

if you have some "error getting text":
- search the string in the english file (languages/english/lang.inc)
- copy to your language file (languages/your_lang/lang.inc)
- translate it

If there is no help in your language:
- Copy the English help (english/help.htm) file to your language folder
- translate it

If you apply any changes to the language files please send them to the
letoDMS developers (www.letodms.com).

BEFORE YOU START =========================================================

letoDMS has changed its installation process with version 3.0.0. This gives
you many more options in how to install letoDMS. First of all, letoDMS was
split into a core package (LetoDMS_Core-<version>.tar.gz) and the web
application itself (letoDMS-<version>.tar.gz). The core is a pear package
which could be installed as one. It is responsible for all the database
operations. The web application contains the gui not knowing anything about
the database layout. Second, one letoDMS installation can be used for
various customer instances by sharing a common source. Starting with
version 3.2.0 a full text search engine has been added. This requires
the zend framework and another pear package LetoDMS_Lucene-<version>.tar.gz
which can be downloaded from the letoDMS web page. Finally, letoDMS has
got a web based installation, which takes care of most of the installation
process.

Before you proceed you have to decide how to install letoDMS:
1. with multiple instances
2. as a single instance

Both have its pros and cons, but
1. setting up a single instance is easier if you have no shell access to
   the web server
2. the installation script is only tested on single instances

Installation for multiple instances shares the same source by many
instances but requires to create links which is not in any case possible
on your web server.

0. Some preparation =======================================================

A common source of problems in the past have been the additional software
packages needed by letoDMS. Those are the PEAR packages Log and
HTTP_WebDAV_Server as well as Zend_Framework and ADOdb.
If you have full access to the server running a Linux distribution it is
recommended to install those with your package manager if they are provided
by your Linux distribution. If you can not install it this way then choose
a directory (preferable not below your web document root), unpack the
software into it and extend the php include path with your newly created
directory. Extending the php include can be either done by modifying
php.ini or adding a line like

php_value include_path '/home/mypath:.:/usr/share/php'

to your apache configuration. Do not forget to add the standard include_path.
Another way to make letoDMS find all the additional software relies on the
ADOdb path in the configuration. The ADOdb path also extends the php
include path. This is done very early during the page creation. Consequently
all software installed below this path is found as well.

For both the LetoDMS_Core and LetoDMS_Lucene package the path can be set
in the configuration, but you can also install them like ADOdb and Log
somewhere in the php include path.

1. Using the installation tool ============================================

Unpack LetoDMS-<version>.tar.gz and LetoDMS_Core-<version>.tar.gz on
your web server. For the full text search engine support, you will also
need to unpack LetoDMS_Lucene-<version>.tar.gz. For the following instructions
we will assume the files of LetoDMS-<version>.tar.gz are accessible through
http://localhost/letodms/

* Point you web browser towards http://hostname/letodms/install/

* Follow the instructions on the page and create a file ENABLE_INSTALL_TOOL
  in the conf directory.

* Create a data directory with the two sub directories staging and lucene.
  Make sure the data directory is either *not* below your document root
	or is protected with a .htaccess file against web access. The data directory
  needs to be writable by the web server.

* Clicking on 'Start installation' will show a form with all necessary
  settings for a basic installation.

* After saving your settings succesfully you are ready to log in as admin and
  continue customizing your installation with the 'Admin Tools'

2. Detailed installation instructions (single instance) =====================

You need a working web server with MySQL/PHP5 support and the files
LetoDMS-<version>.tar.gz and LetoDMS_Core-<version>.tgz. For the 
full text search engine support, you will also need to unpack
LetoDMS_Lucene-<version>.tgz.

* Unpack all the files in a public web server folder. If you're working on
  a host machine your provider will tell you where to upload the files.
  If possible do not unpack LetoDMS_Core-<version>.tgz and
  LetoDMS_Lucene-<version>.tgz. below the document root of your web server.
  Since they are pear packages they can also be installed with 'pear install
  LetoDMS_Core-<version>.tgz' and 'pear install LetoDMS_Lucene-<version>.tgz'

* Unless ADODB is not already installed on your system, download
  (http://adodb.sourceforge.net/) and unpack it in the letoDMS 
  directory

* The PEAR package Log is also needed. It can be downloaded from
  http://pear.php.net/package/Log. Unpack it a place where it can be
  found by php.

* The package HTTP_WebDAV_Server is also needed. It can be downloaded from
  http://pear.php.net/package/HTTP_WebDAV_Server. Unpack it a place where
	it can be found by php.

* Create a data folder somewhere on your web server including the subdirectories
  staging and lucene and make sure they are writable by your web server,
  but not accessible through the web.

For security reason the data folder should not be inside the public folders
or should be protected by a .htaccess file.

If you install letodms for the first time continue with the database setup.

* Create a new database on your web server
  e.g. for mysql:
	create database letodms;
* Create a new user for the database with all permissions on the new database
  e.g. for mysql:
	grant all privileges on letodms.* to letodms@localhost identified by 'secret';
	(replace 'secret' with you own password)
* Optionally import "create_tables.sql" in the new database
  e.g. for mysql:
	cat create_tables.sql | mysql -uletodms -p letodms
  This step can also be done by the install tool.
* create a file ENABLE_INSTALL_TOOL in the conf directory and point
  your browser at http://host/<letodms-dir>/install


NOTE: UPDATING FROM A PREVIOUS VERSION

- make a backup archive of your installation folder
- make a backup archive of your data folder
- dump your current database
- extract the letoDMS archive to your web server
- edit the conf/settings.xml file to match your previuos settings 
  (you can even replace the file with your own one eventualy adding by hand
  the missing new parameters)
- create a file ENABLE_INSTALL_TOOL in the conf directory and point
  your browser at http://host/<letodms-dir>/install

The install tool will detect the version of your current letodms installation
and run the required database updates.


3. Requirements ================================================================

letoDMS is a web-based application written in PHP. It uses the MySQL RDBMS to
manage the documents that were uploaded into the application.

Make sure you have PHP 5.0 and MySQL 5 or higher installed. letoDMS
will work with PHP running in CGI-mode as well as running as module under
apache. If you want to give your users the opportunity of uploading passport
photos you have to enable the gd-library (but the rest of letoDMS will
work without gd, too).

You will also need to download and install the ADODB database
abstraction library from http://adodb.sf.net/ unless it is not installed
on your system already. The webdav server uses the pear packages 'Log' and
'HTTP_WebDAV_Server'. Both can be downloaded from http://pear.php.net.

If you plan to use the full text search engine you will have to install
the zend framework, too.


4. Email Notification ==========================================================

A notification system allows users to receive an email when a
document or folder is changed. This is an event-based mechanism that
notifies the user as soon as the change has been made and replaces the
cron mechanism originally developed. Any user that has read access to a
document or folder can subscribe to be notified of changes. Users that
have been assigned as reviewers or approvers for a document are
automatically added to the notification system for that document.

A new page has been created for users to assist with the management of
their notification subscriptions. This can be found in the "My Account"
section under "Notification List".


5. Auto-conversion to HTML =====================================================

Version 1.3.0 introduces a new feature: Documents can automatically be
converted to HTML when uploading.
You can enable this feature by setting enableConverting (in 
settings.xml) to true.
You will also need to edit convertFileTypes (again in 
settings.xml). This array defines which file-types are converted
and how.
Under windows Word-, Excel- and Powerpoint-Files are automatically
converted using js-Scipts and MS-Office. I tested it with Office 2000
and it worked just fine.
Under Linux mswordview is used to convert Word-Files by default.
Warning: Getting this feature working can be very tricky but if it
works it is a great enhancement I think.
Especially IIS could cause problems with its IIS-Guest-Account not
having enough rights to execute Word or Excel...
You will also have to edit your httpd.conf to be able to view the converted
files online. Load mod_rewrite and add to following lines to your conf:

  RewriteEngine on
  RewriteCond %{REQUEST_URI} (.*)viewonline/([0-9]+)/([0-9]+)/(.+)$
  RewriteRule (.*)viewonline/([0-9]+)/([0-9]+)/(.+)$ $1op.ViewOnline.php?request=$2:$3 [PT]

IIS Users can download the IIS Rewrite Engine for example:
http://www.qwerksoft.com/products/iisrewrite/

Post any questions to the LetoDMS forum, please.


6. Nearly finished =============================================================

Now point your browser to http://your.server.com/letoDMS-<version>/index.php
and login with "admin" both as username and password.
After having logged in you should first choose "My Account" and
change the Administrator's password and email-address.


CONFIGURING MULTIPLE INSTANCES =================================================

Since version 3.0.0, letoDMS can be set up to run several parallel instances
sharing the same source but each instance has its own configuration. This is
quite useful if you intend to host letoDMS for several customers. This
approach still allows to have diffenrent version of letoDMS installed
and will not force you to upgrade a customer instance, because other
instances are upgraded. A customer instance consists of
1. a directory containing mostly links to the letoDMS source and a
   configuration file
2. a directory containing the document content files
3. a database

1. Unpack the letoDMS distribution =============================================

Actually there is no need to set up the database at this point but it won't
hurt since you'll need one in the next step anyway. The sources of letoDMS
can be anywhere you like. The do not have to be in you www-root. If you just
have access to your www-root directory, then put them there.

2. Setup the instance ==========================================================

Unpack the files as described in the quick installation.

Create a directory in your www-root or use www-root for your instance. In the
second case, you will not be able to create a second instance, because each
instance needs its own directory.

Go into that directory create the following links (<letoDMS-source> is the
directory of your initial letoDMS intallation).

src -> <letoDMS-source>
inc -> src/inc
op -> src/op
out -> src/out
languages -> src/languages
styles -> src/styles
install -> src/install
index.php -> src/index.php

ln -s ../letoDMS-<version>
ln -s src/inc inc
ln -s src/op op
ln -s src/out out
ln -s src/languages languages
ln -s src/styles styles
ln -s src/install install
ln -s src/index.php index.php

Create a new directory named conf and run the installation tool.

Creating the links as above has the advantage that you can easily switch
to a new version and go back if it is necessary. You could even run various
instances of letoDMS using different versions.

3. Create a database and data store for each instance ==========================

Create a database and data store for each instance and adjust the database
settings in conf/settings.xml or run the installation tool.

Point your web browser towards the index.php file in your new instance.

LICENSING ======================================================================

LetoDMS is licensed unter GPLv2

Jumploader is licensed as stated by the author on th web site
(http://jumploader.com/)

-- Taken from web site of jumploader  ---
You may use this software for free, however, you should not:

- Decompile binaries.
- Alter or replace class and/or resource files.
- Redistribute this software under different name or authority.

If you would like a customized version, I can do this for a fee. Don’t hesitate to contact me with questions or comments.