3 Last updated: $Date: 2002/10/25 20:22:10 $
4 ----------------------------------------------------------------
6 Here is a short installation-howto of Mir, somewhat more explicit than
7 the earlier version. Some Debian-specific instructions are given.
12 - tomcat 4.0.4 (4.0.3 and below have some bad bugs) or above (3.3 works too as
13 of 04.04.2002, but this could change)
14 tomcat is available from http://jakarta.apache.org/tomcat/
15 - apache 1.3.x. with mod_jk.so. As far as I can tell the connector for 2.x is
16 still rather undocumented. http://httpd.apache.org
17 - postgres 7.1.x or 7.2.x. http://www.postgresql.org
18 - ant (a java-based make)
19 - jaxp-1.1 (a SAX 2.0 compliant XML parser, comes with ant >= 1.4)
20 - the JAI image framework (Java Advanced Imaging) versin 1.1.1 . get it from
21 java.sun.com. ** NOTE: because JAI uses a native acceration library (a .so)
22 it must be placed in tomcat's "lib" (i.e $TOMCAT_HOME/common/lib) directory and
23 not under the default webapps/Mir/WEB-INF/lib directory **
24 - A good reading of Tomcat, Apache and Postgresql documentation if you are not
25 familiar with any of them. The documentation is available at:
26 http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html,
27 http://httpd.apache.org/docs/ and http://www.postgresql.org respectively.
28 -----------------------------------------------------------------------------
29 -----------------------------------------------------------------------------
30 0. To set all this up on Debian:
32 make sure you have stable, testing, and unstable listings in
33 /etc/apt/sources.list. THen do all the following as root or using sudo!
35 If you already have tomcat, and it's working well with apache, then
36 skip directly to (c). If it's not working well, then make sure you
37 purge _all_ conf files & so forth ( though it never hurts to back them
38 up first). "apt-get remove --purge" may not get rid of everything; try
41 and then delete all the files you find (again, if you're unsure what
42 they are, then back them up first).
46 apt-get install j2sdk1.3 j2sdk1.3-doc
48 JAVA_HOME=/usr/lib/j2sdk1.3; export JAVA_HOME
49 PATH=$PATH:$JAVA_HOME/bin; export PATH
50 (add these lines to your .bashrc as well)
52 (b) Installing Tomcat and Apache
54 As root, do the following:
55 apt-get install apache
56 configure apache by editing httpd.conf:
57 * enable shtml includes:
58 - add LoadModule includes_module /usr/lib/apache/1.3/mod_include.so
59 - make sure your directory contains "Options Includes"
60 * Determine if you need to modify any apache mime-mappings
61 - The web-server host must recognize the .m3u, .pls and other file extensions
62 and send the proper "audio/x-mpegurl" and "audio/x-scpls" mime-types
63 respectively. If the web server is apache, it's easy, just
69 to the file pointed to by the "TypesConfig" command in your apache config
70 file. Or add and equivalent AddType command to your httpd.conf. Of course
71 this assumes that the mod_mime is loaded.
75 apt-get install -t unstable tomcat4 tomcat4-webapps tomcat4-admin
76 --> this gets you tomcat4.1. You can work with tomcat 4.0.4
77 as well, but a couple of specific configuration elements are
78 different. To get 4.0.4, run the following:
79 apt-get install -t testing tomcat4 tomcat4-webapps
80 apt-get install apachelib-java
82 Tomcat will be installed in /usr/share/tomcat4, so you should put
84 CATALINA_HOME=/usr/share/tomcat4; export CATALINA_HOME
85 TOMCAT_HOME=$CATALINA_HOME; export TOMCAT_HOME
87 in your .bashrc; you might as well execute the ocmmand right now as
90 I found it somewhat difficult to get Tomcat and Apache working
91 together, until I emailed the Debian package maintainer, who told
92 me that he had purposely removed the mod_jk.conf-auto function from
93 Tomcat4.1! This is because Debian encourages Tomcat users to
94 switch to mod_webapp instead. You may want to try this option
95 out. I didn't, because I was able to get it working using the
96 JkMount option. So in /etc/apache/httpd.conf, look for a section
99 # The following line is for apacheconfig - DO NOT REMOVE!
100 JkWorkersFile /etc/tomcat/jk/workers.properties
101 Include /var/lib/tomcat/conf/mod_jk.conf
104 This has been insrted by libapache-java to try to get mod_jk to
105 work. unfortunately it doesn't work with Tomcat 4.1, so replace it
109 # The following line is for apacheconfig - DO NOT REMOVE!
110 JkWorkersFile /etc/tomcat/jk/workers.properties
114 JkMount /servlet ajp13
115 jkMount /examples/* ajp13
116 #Include /var/lib/tomcat/conf/mod_jk.conf
118 restart tomcat(as root):
119 /usr/share/tomcat4/bin/shutdown.sh
120 /usr/share/tomcat4/bin/startup.sh
121 restart apache(as root):
124 In your browser, check to see if each pogram is working on its own:
125 http://localhost should give you the debian apache start page
126 http://localhost:8180 should give you the tomcat start page
128 now check to see if mod_jk is allowing the two programs to connect:
129 http://localhost/examples/servlets/index.html should give you the
130 Tomcat example servlets.
132 Once this is working, you should enable the tomcat manager
134 cd /usr/share/tomcat4/conf
135 open tomcat-users.xml in a text editor. Add a line like this:
137 <user username="name" password="password" roles="standard,manager,admin"/>
139 You should now be able to click on the "Manager" link on the Tomcat
140 home page, log in, and use the Manager functions. This is extremely
141 convenient when you're eloading Mir multiple times later on!
143 (c) install postgres:
144 apt-get install postgresql postgresql-client postgresql-doc
145 --> the new postgres package should work fine with Mir. Make sure you
146 enable UNICODE, and if asked about JDBC (you shouldn't be) make sure
147 to enable it as well. if you would like to try a graphical frontend
148 for the database, find one using
150 apt-cache show postgresql
152 fmailiarize yourself with the psql interface, and the function of the
157 http://java.sun.com/products/java-media/jai/downloads/download.html
159 and download the "CLASSPATH for Linux" version of the JAI package
160 (1.1.01 works fine, later versions have not been tested by me) to
161 /usr/share/tomcat4/common/lib
165 cd /usr/share/tomcat4/common/lib
167 gunzip "name_of_file.tar.gz" (don't use the quotes: replace with the
168 real name of the file you downloaded!)
170 tar -xvf "name_of_file.tar"
172 read the instructions in
173 /usr/share/tomcat4/common/lib/jai_whatever_version_you_have/INSTALL-jai.txt
175 Now add the JAI files to your CLASSPATH and LSD_LIBRARY_PATH:
176 JAIHOME=$TOMCAT_HOME/common/lib/jai-1_1_1_01/lib; export JAIHOME
177 CLASSPATH=$JAIHOME/jai_core.jar:$JAIHOME/jai_codec.jar:$JAIHOME/mlibwrapper_jai.jar:$CLASSPATH;
179 LD_LIBRARY_PATH=.:$JAIHOME:$CLASSPATH; export LD_LIBRARY_PATH
181 --> make sure to replace "jai-1_1_1_01" in the above with the
182 version-number of your copy of JAI
183 --> as above, it's a good idea to add these lines to your .bashrc
185 ---------------------------------------------------------------
190 (a). get the latest version:
192 cd to the directory where you would like to install the mir package
198 cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs login
203 cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs co mir
206 (b) customize the config:
209 cp config.properties-dist config.properties
211 now customize config.properties for your needs. config.properties is
212 pretty well-documented, but read it carefully. I had to recompile
213 several times before I got all the pathnames right.
216 (c) configure the perms.sh file if neccessary -- IMPORTANT! READ THIS!
217 We provide a script that sets all files' and direcories' permissions to
218 a quite reasonable state. This script gets automagically called by
219 ant after compilationl. The most important thing you have to do after
220 compiling Mir is to ensure that the log files -- especially
221 dbentity.log -- are not readable by users that could compromise
222 system security, because all passwords and the like will be logged here.
224 cp perms.sh-dist perms.sh
226 Now, change the install directory and group in perms.sh
231 (d) Customize the templates
232 you need to edit the templates before compiling, or not all of your
233 changes will show up in the produced site. If this is too
234 intimidating, don't worry -- you can always recompile! It only takes
238 --> tomcat 4.1 has a different method of composing servlet URL's, so
239 if you are uasing 4.1, you wil need to make some minor changes to
242 look for sections like this:
252 the url-pattern has to change; so replace the above with:
261 make sure to do the same for OpenMir and OutputMir.
264 -------------------------------------------------------------
265 -------------------------------------------------------------
266 IMPORTANT! It is a good idea to skip ahead to (2) and create the
267 Postgres database at this point. Then cd back to the mir directory,
269 -------------------------------------------------------------
270 -------------------------------------------------------------
272 (f) compile. Make sure all the environment variables are set as
273 indicated in section (0), or build.xml will not run properly:
278 This should take about a minute. If you don't get an error, run
283 Do this as root so the permissions script is able to set
284 the permissions and owners correctly.
287 (g) Get Tomcat to recognize Mir.
288 Link in the webapps directory of tomcat to the install directory
289 (unless you changed the setting in config.properties, the
290 directory is called "Mir" and is located in the same directory in which
291 you installed the "mir" directory). (Here and in the rest of this document,
292 we assume you called the link "Mir", but this could be named anything.)
293 cd /path/to/tomcat/webapps (tomcat-4.0.x/webapps)
294 ln -s /path/to/Mir Mir
296 dynamically reload Mir:
298 http://localhost:8180/manager/stop?path=/Mir
299 if you're not using the Debian installation, you need to use:
300 http://localhost:8080/manager/stop?path=/Mir
302 if you're using Tomcat 3.3, you need to restart Tomcat (consult the
303 docs for how to do that).
306 (h) Copy any dynamic library files ending with ".so" (so far only the JAI native
307 acceleration library found in the JAI package tarball or zip from sun) to your
308 $JAVA_HOME/jre/lib/i386 directory (where the other ".so" files live). Or, you
309 can skip the whole thing and live without "native" acceleration for image
312 (2) CREATE AND CONLFIGURE THE MIR DATABASE!
314 Review mir/etc/config.properties. Look carefully at the entries you
315 put in the DATABASE SETUP section, especially the Username, Password,
316 Host, and Name variables. If you don't know anything about Postgres,
317 look over the INSTALL.postgresql document, which is very helpful (but
318 remember, you don't need to install postgresql from scratch
319 anymore if you're on Debian woody!). Please do not use the "postgres"
320 user in config.properties -- this is a serious security risk. Choose
321 a username,a password, and a database name, then put those values in
322 config.properties if you haven't already.
324 (a) Create the new database
326 We create and configure the database as posgresql user "postgres":
328 createdb -U postgres --encoding=unicode Mir
329 --> here and elsewhere, replace "Mir" with the name you already chose
333 (b) create an unprivileged database user for Mir
334 First, connect to the database as the database's superuser.
338 Now we create the actual user. Please choose a password that is hard to
339 guess instead of "joshua". Good passwords have characters and numerals in
340 it, have no link to its owner (like being her birthday, age, name of her
341 husband, dog, child, car, favourite beer brand). A good password looks like
344 CREATE USER Mir WITH PASSWORD 'joshua' NOCREATEDB NOCREATEUSER;
345 --> again, don't just copy this into the psql command line -- replace
346 "Mir" and "joshua" with your username and password from config.properties
352 (c) create base table
353 cd back to the mir home directory. now execute the following:
355 psql -Upostgres -f dbscripts/create_pg.sql Mir
358 back in the shell, execute the dbscripts:
359 for i in dbscripts/help*.sql ; do psql -Upostgres -f $i Mir ; done
360 for i in dbscripts/populate*.sql ; do psql -Upostgres -f $i Mir ; done
362 (d) Grant the required permissions to the new user
363 First, make your new user into the database administrator for the new
364 database (instead of postgres):
366 select * from pg_database;
367 select * from pg_user;
368 you'll see a display like this:
369 usename | usesysid | usecreatedb | usetrace | usesuper | usecatupd | passwd | valuntil
370 --------------+----------+-------------+----------+----------+-----------+----------+----------
371 postgres | 1 | t | t | t | t | ******** |
372 matt | 100 | t | f | t | t | ******** |
373 mir | 101 | f | f | f | f | ******** |
377 datname | datdba | encoding | datistemplate | datallowconn | datlastsysoid | datvacuumxid | datfrozenxid | datpath
378 -----------+--------+----------+---------------+--------------+---------------+--------------+--------------+---------
380 template1 | 1 | 5 | t | t | 16554 | 11258 | 3221236731 |
382 template0 | 1 | 5 | t | f | 16554 | 49 | 49 |
384 Mir | 1 | 5 | f | t | 16554 | 10805 | 3221236278 |
386 note the "usesysid" column for your new user, and the datname for your
387 new database. now execute the following line, obviousjly using the
388 variable you just noted:
390 update pg_database set datdba=USESYSID_FROM_PG_USER where datname=DATABASENAME
395 save the following lines to a file called set.permissions:
397 select 'grant all on '||relname||' to Mir;'
399 where relname not like 'pg%'
402 -->be sure to replace "Mir" with your username!!!
404 (e) Apply neccessary changes to config.properties
406 --> if you folowed the instructions above, you shouldn't have to do
407 this, but doublecheck!
408 Please open config.properties and look for the lines that begin with
409 "Database.". The interesting properties are "Username", "Password", "Host"
410 and "Name". Change these properties so that they reflect the settings you
411 used to create the database and the user.
413 You should make sure that no copy of config.properties (neither in mir nor
414 in Mir/src nor in Mir/WEB-INF/classes nor in the directory tree you compiled
415 Mir from) is world-readable. Else you wouldn't have to install a password,
418 (f) Setup PostgreSQL so that all connections have to pass a password
420 In /etc/postgresql/pg_hba.conf you should make sure that nobody can
421 use the database without a password, by inserting these lines:
424 host all 127.0.0.1 255.0.0.0 password
425 host all 0.0.0.0 0.0.0.0 reject
427 make sure you comment out all other permissions lines in this file!
429 This means: All local connections (i.e. psql without "-h hostname" option)
430 have to authenticate themselves with a password. All connections from
431 localhost (127.0.0.1) have to supply a password, too. All other connections
432 are rejected. This line doen't have to be there if you have a properly
433 configured firewall but even if you do have one, it adds to the security in
434 case an attacker penetrates the firewall by some hack.
436 If you can't access PostgreSQL after this for any reason, try and change
437 "password" in /etc/postgresql/pg_hba.conf to "trust". This should disable
438 any authentication method and make the database accessible again. Please use
439 this setting only temporarily because anybody who can access the PostgreSQL
440 server could take over the database completely this way. After you fixed
441 your password setting, switch the setting back to "password".
442 You may want to change your PostgreSQL password from time to time to make
443 database takeover harder. Rememer: Security is a process.
445 ----------------------------------------------------------------
447 AT THIS POINT YOU SHOULD HAVE A WORKING INSTAATION OF MIR! CHECK TO
448 MAKE SURE -- DON'T BOTHER WITH THE REST TILL YOIU'VE MADE MIR WORK ONCE!
453 (3) Add the dupe prevention trigger to the database:
454 cd mir/dbscripts/dupetrigger
456 There, read INSTALL and follow the instructions.
459 (4) Tweak mime-type extensions mappings in etc/web.xml file.
461 *** Note the defaults should be o.k for most installations ***
463 Add or remove any mime types you wish to support. This is used to figure
464 out the mime-type when (broken browsers?) browsers don't send the mime-type
465 in the content-type header field when uploading a media file. Note add the
466 moment you still have to add these to the media_type SQL table as well which
467 maps the mime-types to the correct mediaHandler class. See the comments in
468 the MirMedia class in javadoc for more details.
475 * set the document root to the same directory as in the mir config file
476 * enable shtml includes:
477 - add LoadModule includes_module /usr/lib/apache/1.3/mod_include.so
478 - make sure your directory contains "Options Includes"
479 * Determine if you need to modify any apache mime-mappings
480 - The web-server host must recognize the .m3u, .pls and other file extensions
481 and send the proper "audio/x-mpegurl" and "audio/x-scpls" mime-types
482 respectively. If the web server is apache, it's easy, just
488 to the file pointed to by the "TypesConfig" command in your apache config
489 file. Or add and equivalent AddType command to your httpd.conf. Of course
490 this assumes that the mod_mime is loaded.
494 now the admin-application is accesable via:
496 http://host/Mir/servlet/Mir
498 and the openposting-servlet via
500 http://host/Mir/servlet/OpenMir
502 standard login is admin/indymedia. See the webdb_users SQL table to change/add
508 The Mir code offers no internal search facilities, rather, the design
509 expects the use of an external program to crawl and index the static
510 site. One (recommended) tool for doing this is htdig
511 (http://htdig.org), which generates static databases of the site
512 content and then accesses those databases through a very fast CGI
513 program written in C. In the scripts directory, a perl CGI script
514 which wraps calls to htsearch is provided (scripts/search.pl) which
515 will allow searching based off of media type. (This is possible
516 because the standard templates will include META keywords like
517 hasAudio, hasVideo, etc.)
521 see the UPGRADING.mir file.
525 You can give these a try if anything goes wrong:
527 + Restart Tomcat. Especially after compiling the sources Tomcat has to be
530 + Check file permissions and ownership. Try and run perms.sh.
532 ----------------------------------------------------------------
534 $Date: 2002/10/25 20:22:10 $ - the Mir coders