| 1 |
<h1>Installation instructions</h1> |
| 2 |
|
| 3 |
<p><small>Just <a href="upgrade.html">upgrading from v1.x</a> or |
| 4 |
<a href="upgrade.html#cvs">updating to latest v2.x version</a>? |
| 5 |
</small> |
| 6 |
</p> |
| 7 |
|
| 8 |
<ol> |
| 9 |
<li>You will need <a href="http://www.apache.org/">Apache</a> web server |
| 10 |
(it should work with version 1.3 or 2.0, but it's not tested with 2.0) |
| 11 |
and <a href="http://www.php.net/">php</a> version 4.x installed and |
| 12 |
configured for docman to work. |
| 13 |
<small><a href="faq.html#php3">related FAQ question</a></small> |
| 14 |
<li>Get latest version of Document Manager from |
| 15 |
<a href="http://www.rot13.org/~dpavlin/docman.html"> |
| 16 |
http://www.rot13.org/~dpavlin/docman.html</a> |
| 17 |
|
| 18 |
<li>Go to installation directory (which <b>shouldn't be</b> under your web |
| 19 |
server's DocumentRoot) and untar distribution |
| 20 |
<pre> |
| 21 |
cd /home/httpd |
| 22 |
tar xvfz docman-2*.tar.gz |
| 23 |
</pre> |
| 24 |
Make a symlink from current version (2.x) to default directory name |
| 25 |
<tt>docman2</tt> |
| 26 |
<pre> |
| 27 |
ln -s docman-2.x docman2 |
| 28 |
</pre> |
| 29 |
If you decide to install docman in some other directory, change |
| 30 |
<tt>$gblIncDir</tt> to that directory in <a href="#realm"> |
| 31 |
<tt>realm/http_virtual_host.conf</tt></a>! |
| 32 |
<br>If you don't want to use virtual hosts to separate docman |
| 33 |
installations on same host, but instead use directory name before |
| 34 |
<tt>docman.php</tt> script please read whole installation instructions |
| 35 |
and than <a href="admin.html#path_realm">Using script path as realm name</a> |
| 36 |
to correct all instructions. |
| 37 |
|
| 38 |
<li>Go to directory which you want to have under Document Manager control |
| 39 |
(this directory also <b>shouldn't be</b> accessible from your web server |
| 40 |
tree) |
| 41 |
<pre> |
| 42 |
cd /home/httpd/repository |
| 43 |
</pre> |
| 44 |
chmod that directory so that web server can write in it. |
| 45 |
<pre> |
| 46 |
chown nobody /home/httpd/repository |
| 47 |
</pre> |
| 48 |
|
| 49 |
If you use <a href="http://www.debian.org/">Debian</a> you will want |
| 50 |
to use <tt>www-data</tt> user like this: |
| 51 |
<tt>chown www-data /home/httpd/repository</tt> |
| 52 |
|
| 53 |
<li>Make a symlink from that directory to file which will be directory index |
| 54 |
<pre> |
| 55 |
ln -s /home/httpd/docman2/docman.php \ |
| 56 |
/home/httpd/http_virtual_host/index.php |
| 57 |
</pre> |
| 58 |
|
| 59 |
<a name="docman.css"> |
| 60 |
<li> <i>optional, performance</i> |
| 61 |
Make a symlink from docman.css file to your web-exported directory |
| 62 |
<pre> |
| 63 |
ln -s /home/httpd/docman2/html/docman.css \ |
| 64 |
/home/httpd/http_virtual_host/docman.css |
| 65 |
</pre> |
| 66 |
|
| 67 |
<a name="docman_conf"> |
| 68 |
<li>Copy docman <a href="upgrade.html#docman_conf">master configuration</a> |
| 69 |
file to <tt>/etc/docman.conf</tt>. If you |
| 70 |
want, you can change location of that file (so it's not in <tt>/etc</tt>) |
| 71 |
on top of <tt>docman.php</tt> |
| 72 |
but that will break automatic cvs update |
| 73 |
<small>(see <a href="upgrade.html#cvs">upgrade via CVS</a>)</small> |
| 74 |
<pre> |
| 75 |
cp /home/httpd/docman2/docman.conf /etc/docman.conf |
| 76 |
</pre> |
| 77 |
If you haven't installed docman in <tt>/home/httpd/docman2</tt> change |
| 78 |
<tt>$gblIncDir</tt> to your installation directory. |
| 79 |
<br>You can also enter values for <tt>$fsRealmDir</tt> (normally |
| 80 |
set to <tt>$gblIncDir/realm</tt>) there (and to some location |
| 81 |
which is not your docman installation). |
| 82 |
|
| 83 |
<a name="realm"> |
| 84 |
<li>Go into docman's <tt>realm</tt> directory and copy template configuration |
| 85 |
into your <tt>http_virtual_host.conf</tt> |
| 86 |
<pre> |
| 87 |
cp /home/httpd/docman2/realm/localhost.conf.dist \ |
| 88 |
/home/httpd/docman2/realm/http_virtual_host.conf |
| 89 |
</pre> |
| 90 |
More about <a href="new_directory_layout.html#realm">realms</a> can |
| 91 |
be found elsewhere in documentation. |
| 92 |
|
| 93 |
<br><b>Be sure to change</b> <tt>$gblRepositoryDir</tt> in |
| 94 |
<tt>realm/http_virtual_host.conf</tt> to match your repository |
| 95 |
directory (the one with user files and writable by web server). |
| 96 |
|
| 97 |
<li>Make Apache Virtual Host configuration for hostname <i>http_virtual_host</i> |
| 98 |
to point to <tt>/home/httpd/http_virtual_host</tt>. |
| 99 |
|
| 100 |
<br>How to do that is beyond scope of this document. Please examine |
| 101 |
<a href="http://httpd.apache.org/docs-project/">Apache documentation</a>. |
| 102 |
|
| 103 |
<br>If you don't want to use virtual hosts for docman installation, your |
| 104 |
realm will be called the same as ServerName. |
| 105 |
|
| 106 |
<br>Add new DirectoryIndex entry to your Apache configuration file. If you |
| 107 |
are using virtual hosts, add it there. If your |
| 108 |
Apache has config files in <tt>/etc/httpd/conf/httpd.conf</tt> find a line |
| 109 |
like |
| 110 |
<pre> |
| 111 |
DirectoryIndex index.html index.htm |
| 112 |
</pre> |
| 113 |
and add <tt>index.php</tt> at the end. |
| 114 |
<pre> |
| 115 |
DirectoryIndex index.html index.htm index.php |
| 116 |
</pre> |
| 117 |
|
| 118 |
<i>Hint!</i> |
| 119 |
|
| 120 |
You might want to include something like: |
| 121 |
<pre> |
| 122 |
<Directory /home/httpd/http_virtual_host> |
| 123 |
Options +FollowSymLinks |
| 124 |
</Directory> |
| 125 |
</pre> |
| 126 |
if you get error "Symbolic link not allowed" in Apache's <tt>error.log</tt>. |
| 127 |
|
| 128 |
<li><i>if you don't want to users in SQL database</i> |
| 129 |
Go to you web server <tt>http://http_virtual_host/</tt> and you should get |
| 130 |
authorization request. If you want to add |
| 131 |
<a href="trustee.html#anonymous">anonymous access</a> (without |
| 132 |
login and password) skip to <a href="#trustee">trustee</a> section. |
| 133 |
|
| 134 |
<br>Edit <tt>realm/http_virtual_host.htusers</tt> file to add users. |
| 135 |
You can do that by calling <tt>adduser.pl</tt> script with name of |
| 136 |
your htusers file like this: |
| 137 |
<pre> |
| 138 |
$ cd /home/httpd/docman2 |
| 139 |
$ ./adduser.pl realm/http_virtual_host.conf |
| 140 |
</pre> |
| 141 |
If you press just <i>enter</i> for password or enter <tt>auth_pop3</tt> |
| 142 |
docman will use e-mail address to connect to pop3 server and check |
| 143 |
password on it. For that e-mail address must be in following form: |
| 144 |
<tt>pop3login@pop3server.mydomain</tt> |
| 145 |
|
| 146 |
<br>E-mail addresses are also used for notification of changes in |
| 147 |
repository, so if your pop3 account is not a valid e-mail address that |
| 148 |
won't work for you. |
| 149 |
<br>However, one of planned enhancements is e-mail notification to |
| 150 |
addresses which are not from htusers file, so watch out. |
| 151 |
|
| 152 |
<li> <i>alternative your users are in SQL database</i> |
| 153 |
Change <tt>$gblUsers</tt> |
| 154 |
in <tt>realm/http_virtual_host.conf</tt> to |
| 155 |
<tt>$gblUsers = "htusers_sql";</tt> |
| 156 |
|
| 157 |
<p><i>Since I will convert all code to use PEAR, you again have to |
| 158 |
download php-dbi classes, because they are not included with docman |
| 159 |
anymore. This feature is not tested in version 2.0. Look out!</i></p> |
| 160 |
|
| 161 |
<br>Download php-dbi class from |
| 162 |
<a href="http://pil.dk/downloads/"> |
| 163 |
http://pil.dk/downloads/dbi*.tar.gz</a> and |
| 164 |
untar it in docman's directory |
| 165 |
<pre> |
| 166 |
cd /home/httpd/docman2 |
| 167 |
tar xvfz dbi.tar.gz |
| 168 |
</pre> |
| 169 |
Construct SQL query which returns login, full name, password and |
| 170 |
email from your tables(s). If you don't have some of that data, replace |
| 171 |
them with literal strings. |
| 172 |
<blockquote> |
| 173 |
e.g. If your table is called <tt>my_users</tt> with columns <tt>who</tt> |
| 174 |
in which is login and column <tt>pw</tt> in which is plain text |
| 175 |
password you can use following query to get requested format: |
| 176 |
<br><tt>select who,'Auth user',pw,'nobody@com' from my_users</tt> |
| 177 |
</blockquote> |
| 178 |
|
| 179 |
Enter that SQL query under <tt>$dbi_sql</tt> in |
| 180 |
<tt>realm/http_virtual_host.conf</tt>. |
| 181 |
|
| 182 |
<br>Construct <tt>$dbi</tt> in <tt>realm/http_virtual_host.conf</tt> |
| 183 |
in following format: |
| 184 |
<pre> |
| 185 |
$dbi = "driver:database:user:password" |
| 186 |
</pre> |
| 187 |
|
| 188 |
Field <i>driver</i> can be: <tt>pgsql</tt>, <tt>mysql</tt>, <tt>oracle</tt> |
| 189 |
or <tt>odbc</tt> (or other if supported by current php-dbi), <i>database</i> |
| 190 |
is name of database in which are your users and <i>user</i>/<i>password</i> |
| 191 |
are credentials for user which connects to database. |
| 192 |
|
| 193 |
<li> <i>alternative if you want to authorize users based on IP numbers, |
| 194 |
client DNS names of HTTP Referrer header (URL from which they accessed |
| 195 |
docman site)</i> |
| 196 |
<br>Put <tt>$gblUsers = "htusers_header";</tt> in |
| 197 |
<tt>realm/http_virtual_host.conf</tt> and use |
| 198 |
following form in your <tt>realm/http_virtual_host.htusers</tt> file: |
| 199 |
<pre> |
| 200 |
REMOTE_ADDR=10.0.0.3:Full name:auth_header:e-mail@foo.bar |
| 201 |
remote_hostname=myworkstation:Full name:auth_header:e-mail@foo.bar |
| 202 |
http_referer=test.foo.bar:Full name:auth_header:e-mail@foo.bar |
| 203 |
</pre> |
| 204 |
Please note that you <b>have to</b> put <tt>auth_header</tt> in password |
| 205 |
field and valid options in login field. |
| 206 |
<br>Valid options for left side of equation (=) in login field are: |
| 207 |
<tt>remote_addr</tt>, <tt>remote_hostname</tt> or <tt>http_referer</tt>. |
| 208 |
Valid filed for right side are respective parameters for that option. |
| 209 |
|
| 210 |
<li> <i>if you want some combination of above auth methods</i> |
| 211 |
<br>Put in <tt>realm/http_virtual_host.conf</tt>: |
| 212 |
<br><tt>$gblUsers = "htusers_union"</tt><br> |
| 213 |
and uncomment which htusers auth modules you want to use and in which |
| 214 |
order. It's enough for just one module to return success and user will |
| 215 |
be allowed to login (so you can first check http_referer and then |
| 216 |
htusers file if you want to). |
| 217 |
|
| 218 |
<a name="trustee"> |
| 219 |
<li> <i>optional, but highly recommended</i> |
| 220 |
Trustees are ACL implementation in docman. It's documented in |
| 221 |
<a href="trustee.html">separate document</a>, and you should use it if your |
| 222 |
users shouldn't have same right to all files under docman control, or |
| 223 |
if you want to enable <a href="trustee.html#anonymous">anonymous |
| 224 |
access</a> to repository. |
| 225 |
|
| 226 |
<li> <i>optional</i> You can create file named <tt>.info.inc</tt> in |
| 227 |
<tt>/home/httpd/repository</tt> directory for some kind of |
| 228 |
<acronym title="message of the day">motd</acronym> |
| 229 |
file. You can use html mark-up in it also! |
| 230 |
|
| 231 |
<li> <i>optional</i>If you decided to use |
| 232 |
<a href="admin.html#path_realm">script path as realm name</a> |
| 233 |
correct all installation files according to |
| 234 |
<a href="admin.html#path_realm_convert">this instructions</a>. |
| 235 |
|
| 236 |
<li> if you want to <b>upload files which are bigger than 2Mb</b> increase |
| 237 |
<tt>upload_max_filesize</tt> to more than 2Mb in <tt>php.ini</tt>. |
| 238 |
If you still get errors on files bigger than 8Mb increase |
| 239 |
<tt>post_max_size</tt> also. |
| 240 |
|
| 241 |
<li> <i>optional</i> Think about configuring your backup software so that |
| 242 |
<tt>/home/httpd</tt> is backup ed automatically. |
| 243 |
|
| 244 |
<li> <i>optional</i> You can use document manager behind secure http |
| 245 |
server (<tt>https</tt>) simply by installing it. For information take a |
| 246 |
look at <a href="http://www.modssl.org">http://www.modssl.org</a> |
| 247 |
if you are using Apache 1.x or examine configuration options |
| 248 |
for Apache 2.x. |
| 249 |
|
| 250 |
<a name="gblSeparateAdminMessages"> |
| 251 |
<li> <i>optional, after you are sure that configuration if correct</i> |
| 252 |
You can separate administrative messages from errors which are |
| 253 |
reported to users using |
| 254 |
<tt>$gblSeparateAdminMessages = 1</tt> |
| 255 |
in <tt>realm/http_virtual_host.conf</tt>. Error messages for you |
| 256 |
will go to Apache Error log, and (if you also setup |
| 257 |
<tt>$gblMailAdminMessages = 1</tt> to ServerAdmin from |
| 258 |
<tt>apache.conf</tt>). |
| 259 |
|
| 260 |
</ol> |
| 261 |
|
| 262 |
<p><b>You are ready to go.</b></p> |
| 263 |
|
| 264 |
<p> |
| 265 |
More info see: <a href="new_directory_layout.html">New Directory Layout</a>, |
| 266 |
<a href="upgrade.html">How to Upgrade from v1.x</a>, |
| 267 |
<a href="performance.html">Performance tips</a> and |
| 268 |
<a href="admin.html">Administration manual</a> |
| 269 |
</p> |
Parent Directory
| 
Revision Log