added UPGRADING tips
[mir.git] / doc / INSTALL.mir
1 MIR INSTALLATION HOWTO
2 ----------------------------------------------------------------
3
4 Here is a short installation-howto of Mir.
5
6
7 prerequisites: 
8
9 - tomcat 4.0.3 or above (3.3 works too as of 04.04.2002, but this could change)
10   tomcat is available from http://jakarta.apache.org
11 - apache with mod_jk.so
12 - postgres 7.1.x or 7.2.x
13 - ant (a java-based make) 
14 - jaxp-1.1 (a SAX 2.0 compliant XML parser, comes with ant >= 1.4)
15 - the JAI image framework (Java Advanced Imaging) versin 1.1.1 . get it from 
16   java.sun.com. ** NOTE: because JAI uses a native acceration library (a .so)
17   it must be placed in tomcat's "lib" (i.e $TOMCAT_HOME/lib) directory and
18   not under the default webapps/Mir/WEB-INF/lib directory **
19
20 1. checkout the cvs
21
22 CVS LOGIN:
23
24   cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs login
25         password: anonymous
26
27 CVS CHECKOUT:
28
29         cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvsco mir 
30
31
32 2. customize the config: 
33
34         cd mir/source 
35         cp config.properties-dist config.properties 
36
37 now customize config.properties for your needs.
38
39
40 3. configure the perms.sh file if neccessary -- IMPORTANT! READ THIS!
41 We provide a script that sets all files' and direcories' permissions to
42 a quite reasonable state. This script gets automagically called by
43 ant after compilationl. The most important thing you have to do after
44 compiling Mir is to ensure that the log files -- especially 
45 dbentity.log -- are not readable by users that could compromise 
46 system security, because all passwords and the like will be logged here.
47         
48         cp perms.sh-dist perms.sh
49
50 Now, change the install directory and group in perms.sh
51
52         edit perms.sh 
53
54
55 4. copy the mir/templates-dist-directory to mir/templates
56
57
58 5. compile. For this step, you have to make sure that the TOMCAT_HOME
59 environment variable is set to the root of your tomcat installation.
60 The build.xml compile target will give up if this is not set.
61
62 Do this as root so the permissions script is able to set
63 the permissions and owners correctly.
64
65     ant 
66
67
68 6. Link in the webapps directory of tomcat to the install directory (the 
69 directory is called "Mir" and is located in the same directory in which 
70 you installed the "mir" directory). 
71         cd /path/to/tomcat/webapps (tomcat-4.0.x/webapps)
72         ln -s Mir-install-dir Mir
73
74 with tomcat 4.0.x, you could dynamically reload and stop the Mir webapp without
75 restarting tomcat by using the "Manager App" with the following url:
76
77 http://localhost:8080/manager/stop?path=/mir
78
79 This is practical if you are running several installations of mir on one 
80 tomcat or other webapps and can't afford to shutdown all of them.
81 See the tomcat documentation to learn how to enable and use the manager app.
82
83 7. Copy any dynamic library files ending with ".so" (so far only the JAI native
84 acceleration library found in the JAI package tarball or zip from sun) to your
85 $JAVA_HOME/jre/lib/i386 directory (where the other ".so" files live). Or, you
86 can skip the whole thing and live without "native" acceleration for image
87 manupulation.
88
89 8a. create a new database 
90 The database name should be the same as in config.properties. Please look at
91 the section "Database.*" to look up the names or change them to your needs. 
92
93 It is wise in terms of system seurity to use an unprivileged user for this
94 task instead of the superuser. This is because if Mir uses the superuser to
95 connect to the database and anybody manages to find out the password Mir 
96 uses to connect, the attacker can take over the complete database. So, in
97 the following examples, we assume that the database name is "Mir", the
98 database user will be "mir" and the password is "joshua". Please note that
99 this particular password is far from being a good one. Watch "Wargames" for
100 details. =B) 
101
102 To access the database as the database superuser, you either have to log in
103 as postgres on Unix level (which we don't recommend because you will need
104 another user to have a login shell and a password which makes system
105 penetration more likely) or you have to tell PostgreSQL with each
106 application call that you want to connect as a specific user. If you access
107 the database from any other user's account, use the -U flag to connect to
108 PostgreSQL as the database superuser ("postgres"):
109
110         createdb -U postgres --encoding=unicode Mir 
111
112 Please note that if you create the database from inside the psql application,
113 the database name will likely be converted to lowercase letters.
114
115
116 8b. create an unprivileged database user for Mir
117 First, connect to the database as the database's superuser. 
118
119         psql -U postgres Mir
120
121 Now we create the actual user. Please choose a password that is hard to 
122 guess instead of "joshua". Good passwords have characters and numerals in
123 it, have no link to its owner (like being her birthday, age, name of her 
124 husband, dog, child, car, favourite beer brand). A good password looks like
125 this: "8ncx4un".
126     
127     CREATE USER Mir WITH PASSWORD 'joshua' NOCREATEDB NOCREATEUSER;
128
129
130 8c. create base table
131 Please note that we use the superuser "postgres" to connect to the "Mir"
132 database, /not/ the user "mir". 
133
134         psql -Upostgres -f dbscripts/create_pg.sql Mir
135     for i in dbscripts/help*.sql ; do psql -Upostgres -f $i Mir ; done
136     for i in dbscripts/populate*.sql ; do psql -Upostgres -f $i Mir ; done
137
138
139 8d. Apply neccessary changes to config.properties
140
141 Please open config.properties and look for the lines that begin with
142 "Database.". The interesting properties are "Username", "Password", "Host"
143 and "Name". Change these properties so that they reflect the settings you
144 used to create the database and the user.
145
146 You should make sure that no copy of config.properties (neither in mir nor
147 in Mir/src nor in Mir/WEB-INF/classes nor in the directory tree you compiled
148 Mir from) is world-readable. Else you wouldn't have to install a password,
149 anyway.
150
151 8e. Tweak mime-type extensions mappings in etc/web.xml file.
152
153 *** Note the defaults should be o.k for most installations ***
154
155 Add or remove any mime types you wish to support. This is used to figure
156 out the mime-type when (broken browsers?) browsers don't send the mime-type
157 in the content-type header field when uploading a media file. Note add the
158 moment you still have to add these to the media_type SQL table as well which
159 maps the mime-types to the correct mediaHandler class. See the comments in
160 the MirMedia class in javadoc for more details.
161
162 8f. Setup PostgreSQL so that all connections have to pass a password
163
164 In /etc/postgresql/pg_hba.conf you should make sure that nobody can
165 use the database without a password:
166
167 local            all                                                                               password
168 host         all         127.0.0.1     255.0.0.0           password
169 host         all         0.0.0.0       0.0.0.0             reject
170
171 This means: All local connections (i.e. psql without "-h hostname" option)
172 have to authenticate themselves with a password. All connections from
173 localhost (127.0.0.1) have to supply a password, too. All other connections
174 are rejected. This line doen't have to be there if you have a properly
175 configured firewall but even if you do have one, it adds to the security in
176 case an attacker penetrates the firewall by some hack.
177
178 If you can't access PostgreSQL after this for any reason, try and change
179 "password" in /etc/postgresql/pg_hba.conf to "trust". This should disable
180 any authentication method and make the database accessible again. Please use 
181 this setting only temporarily because anybody who can access the PostgreSQL
182 server could take over the database completely this way. After you fixed
183 your password setting, switch the setting back to "password".
184 You may want to change your PostgreSQL password from time to time to make
185 database takeover harder. Rememer: Security is a process.
186
187
188
189 9. Add the dupe prevention trigger to the database:
190         cd dbscripts/dupetrigger
191         
192         There, read INSTALL and follow the instructions.
193         
194
195 10. restart tomcat 
196
197 11. configure mod_jk 
198
199 insert the following patch into /etc/apache/httpd.conf. Edit the directories
200 to suit your needs.
201
202 <IfModule mod_jk.c>
203 JkWorkersFile /path/to/tomcat/conf/workers.properties
204 Include /path/to/tomcat/conf/mod_jk.conf-auto
205 </IfModule>
206
207 Do not put any JkMount lines into your httpd.conf!
208
209 If mod_jk.conf-auto doesn't get written or is 0 bytes in size, check your
210 system for file ownership/permissions problems.
211
212
213 12. configure apache
214
215 edit http.conf:
216 * set the document root to the same directory as in the mir config file
217 * enable shtml includes:
218   - add LoadModule includes_module /usr/lib/apache/1.3/mod_include.so
219   - make sure your directory contains "Options Includes"
220
221
222 that's it :)
223
224 now the admin-application is accesable via:  
225
226         http://host/Mir 
227
228 and the openposting-servlet via  
229         
230         http://host/OpenMir
231
232 standard login is redaktion/indymedia
233
234
235 SEARCHING
236
237 The Mir code offers no internal search facilities, rather, the design
238 expects the use of an external program to crawl and index the static
239 site.  One (recommended) tool for doing this is htdig
240 (http://htdig.org), which generates static databases of the site
241 content and then accesses those databases through a very fast CGI
242 program written in C.  In the scripts directory, a perl CGI script 
243 which wraps calls to htsearch is provided (scripts/search.pl) which
244 will allow searching based off of media type.  (This is possible
245 because the standard templates will include META keywords like
246 hasAudio, hasVideo, etc.)  
247
248 UPGRADING
249
250 see the UPGRADING.mir file.
251
252 TROUBLESHOOTING
253
254 You can give these a try if anything goes wrong:
255
256 + Restart Tomcat. Especially after compiling the sources Tomcat has to be
257   restarted.
258
259 + Check file permissions and ownership. Try and run perms.sh.
260
261 ----------------------------------------------------------------
262
263 2001, 2002 - the Mir coders