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