Installation instructions

Just upgrading from v1.x or updating to latest v2.x version?

You will need Apache web server (it should work with version 1.3 or 2.0, but it's not tested with 2.0) and php version 4.x installed and configured for docman to work. related FAQ question
Get latest version of Document Manager from http://www.rot13.org/~dpavlin/docman.html
Go to installation directory (which shouldn't be under your web server's DocumentRoot) and untar distribution
```
	cd /home/httpd
	tar xvfz docman-2*.tar.gz
   
```
Make a symlink from current version (2.x) to default directory name docman2
```
   	ln -s docman-2.x docman2
   
```
If you decide to install docman in some other directory, change $gblIncDir to that directory in realm/http_virtual_host.conf!
If you don't want to use virtual hosts to separate docman installations on same host, but instead use directory name before docman.php script please read whole installation instructions and than Using script path as realm name to correct all instructions.
Go to directory which you want to have under Document Manager control (this directory also shouldn't be accessible from your web server tree)
```
	cd /home/httpd/repository
   
```
chmod that directory so that web server can write in it.
```
	chown nobody /home/httpd/repository
   
```
If you use Debian you will want to use www-data user like this: chown www-data /home/httpd/repository

Make a symlink from that directory to file which will be directory index

	ln -s /home/httpd/docman2/docman.php \
	      /home/httpd/http_virtual_host/index.php

optional, performance Make a symlink from docman.css file to your web-exported directory

   	ln -s /home/httpd/docman2/html/docman.css \
	      /home/httpd/http_virtual_host/docman.css

Copy docman master configuration file to /etc/docman.conf. If you want, you can change location of that file (so it's not in /etc) on top of docman.php but that will break automatic cvs update (see upgrade via CVS)
```
   	cp /home/httpd/docman2/docman.conf /etc/docman.conf
   
```
If you haven't installed docman in /home/httpd/docman2 change $gblIncDir to your installation directory.
You can also enter values for $fsRealmDir (normally set to $gblIncDir/realm) there (and to some location which is not your docman installation).
Go into docman's realm directory and copy template configuration into your http_virtual_host.conf
```
   	cp /home/httpd/docman2/realm/localhost.conf.dist \
	   /home/httpd/docman2/realm/http_virtual_host.conf
   
```
More about
realms can be found elsewhere in documentation.
Be sure to change $gblRepositoryDir in realm/http_virtual_host.conf to match your repository directory (the one with user files and writable by web server).
Make Apache Virtual Host configuration for hostname http_virtual_host to point to /home/httpd/http_virtual_host.
How to do that is beyond scope of this document. Please examine Apache documentation.
If you don't want to use virtual hosts for docman installation, your realm will be called the same as ServerName.
Add new DirectoryIndex entry to your Apache configuration file. If you are using virtual hosts, add it there. If your Apache has config files in /etc/httpd/conf/httpd.conf find a line like
```
	DirectoryIndex index.html index.htm
   
```
and add index.php at the end.
```
	DirectoryIndex index.html index.htm index.php
   
```
Hint! You might want to include something like:
```
	<Directory /home/httpd/http_virtual_host>
		Options +FollowSymLinks
	</Directory>
   
```
if you get error "Symbolic link not allowed" in Apache's error.log.
if you don't want to users in SQL database Go to you web server http://http_virtual_host/ and you should get authorization request. If you want to add anonymous access (without login and password) skip to trustee section.
Edit realm/http_virtual_host.htusers file to add users. You can do that by calling adduser.pl script with name of your htusers file like this:
```
   	$ cd /home/httpd/docman2
   	$ ./adduser.pl realm/http_virtual_host.conf
   
```
If you press just enter for password or enter auth_pop3 docman will use e-mail address to connect to pop3 server and check password on it. For that e-mail address must be in following form: pop3login@pop3server.mydomain
E-mail addresses are also used for notification of changes in repository, so if your pop3 account is not a valid e-mail address that won't work for you.
However, one of planned enhancements is e-mail notification to addresses which are not from htusers file, so watch out.
alternative your users are in SQL database Change $gblUsers in realm/http_virtual_host.conf to $gblUsers = "htusers_sql";
Since I will convert all code to use PEAR, you again have to download php-dbi classes, because they are not included with docman anymore. This feature is not tested in version 2.0. Look out!

Download php-dbi class from http://pil.dk/downloads/dbi*.tar.gz and untar it in docman's directory
```
	cd /home/httpd/docman2
	tar xvfz dbi.tar.gz
   
```
Construct SQL query which returns login, full name, password and email from your tables(s). If you don't have some of that data, replace them with literal strings.
e.g. If your table is called my_users with columns who in which is login and column pw in which is plain text password you can use following query to get requested format:
select who,'Auth user',pw,'nobody@com' from my_users
Enter that SQL query under $dbi_sql in realm/http_virtual_host.conf.
Construct $dbi in realm/http_virtual_host.conf in following format:
```
	$dbi = "driver:database:user:password"
   
```
Field driver can be: pgsql, mysql, oracle or odbc (or other if supported by current php-dbi), database is name of database in which are your users and user/password are credentials for user which connects to database.
alternative if you want to authorize users based on IP numbers, client DNS names of HTTP Referrer header (URL from which they accessed docman site)
Put $gblUsers = "htusers_header"; in realm/http_virtual_host.conf and use following form in your realm/http_virtual_host.htusers file:
```
   REMOTE_ADDR=10.0.0.3:Full name:auth_header:e-mail@foo.bar
   remote_hostname=myworkstation:Full name:auth_header:e-mail@foo.bar
   http_referer=test.foo.bar:Full name:auth_header:e-mail@foo.bar
   
```
Please note that you have to put auth_header in password field and valid options in login field.
Valid options for left side of equation (=) in login field are: remote_addr, remote_hostname or http_referer. Valid filed for right side are respective parameters for that option.
if you want some combination of above auth methods
Put in realm/http_virtual_host.conf:
$gblUsers = "htusers_union"
and uncomment which htusers auth modules you want to use and in which order. It's enough for just one module to return success and user will be allowed to login (so you can first check http_referer and then htusers file if you want to).
optional, but highly recommended Trustees are ACL implementation in docman. It's documented in separate document, and you should use it if your users shouldn't have same right to all files under docman control, or if you want to enable anonymous access to repository.
optional You can create file named .info.inc in /home/httpd/repository directory for some kind of motd file. You can use html mark-up in it also!
optionalIf you decided to use script path as realm name correct all installation files according to this instructions.
if you want to upload files which are bigger than 2Mb increase upload_max_filesize to more than 2Mb in php.ini. If you still get errors on files bigger than 8Mb increase post_max_size also.
optional Think about configuring your backup software so that /home/httpd is backup ed automatically.
optional You can use document manager behind secure http server (https) simply by installing it. For information take a look at http://www.modssl.org if you are using Apache 1.x or examine configuration options for Apache 2.x.
optional, after you are sure that configuration if correct You can separate administrative messages from errors which are reported to users using $gblSeparateAdminMessages = 1 in realm/http_virtual_host.conf. Error messages for you will go to Apache Error log, and (if you also setup $gblMailAdminMessages = 1 to ServerAdmin from apache.conf).

You are ready to go.

More info see: New Directory Layout, How to Upgrade from v1.x, Performance tips and Administration manual