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