3 Last updated: $Date: 2003/01/18 08:44:09 $
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.
72 * Make sure that if you are using a non standard character set enconding that
73 Apache doesn't accidentally send the wrong encoding in the HTTP headers.
78 apt-get install -t unstable tomcat4 tomcat4-webapps tomcat4-admin
79 --> this gets you tomcat4.1. You can work with tomcat 4.0.4
80 as well, but a couple of specific configuration elements are
81 different. To get 4.0.4, run the following:
82 apt-get install -t testing tomcat4 tomcat4-webapps
83 apt-get install apachelib-java
85 Tomcat will be installed in /usr/share/tomcat4, so you should put
87 CATALINA_HOME=/usr/share/tomcat4; export CATALINA_HOME
88 TOMCAT_HOME=$CATALINA_HOME; export TOMCAT_HOME
90 in your .bashrc; you might as well execute the ocmmand right now as
93 I found it somewhat difficult to get Tomcat and Apache working
94 together, until I emailed the Debian package maintainer, who told
95 me that he had purposely removed the mod_jk.conf-auto function from
96 Tomcat4.1! This is because Debian encourages Tomcat users to
97 switch to mod_webapp instead. You may want to try this option
98 out. I didn't, because I was able to get it working using the
99 JkMount option. So in /etc/apache/httpd.conf, look for a section
100 like this at the end:
102 # The following line is for apacheconfig - DO NOT REMOVE!
103 JkWorkersFile /etc/tomcat/jk/workers.properties
104 Include /var/lib/tomcat/conf/mod_jk.conf
107 This has been insrted by libapache-java to try to get mod_jk to
108 work. unfortunately it doesn't work with Tomcat 4.1, so replace it
112 # The following line is for apacheconfig - DO NOT REMOVE!
113 JkWorkersFile /etc/tomcat/jk/workers.properties
117 JkMount /servlet ajp13
118 jkMount /examples/* ajp13
119 #Include /var/lib/tomcat/conf/mod_jk.conf
121 restart tomcat(as root):
122 /usr/share/tomcat4/bin/shutdown.sh
123 /usr/share/tomcat4/bin/startup.sh
124 restart apache(as root):
127 In your browser, check to see if each pogram is working on its own:
128 http://localhost should give you the debian apache start page
129 http://localhost:8180 should give you the tomcat start page
131 now check to see if mod_jk is allowing the two programs to connect:
132 http://localhost/examples/servlets/index.html should give you the
133 Tomcat example servlets.
135 Once this is working, you should enable the tomcat manager
137 cd /usr/share/tomcat4/conf
138 open tomcat-users.xml in a text editor. Add a line like this:
140 <user username="name" password="password" roles="standard,manager,admin"/>
142 You should now be able to click on the "Manager" link on the Tomcat
143 home page, log in, and use the Manager functions. This is extremely
144 convenient when you're eloading Mir multiple times later on!
146 (c) install postgres:
147 apt-get install postgresql postgresql-client postgresql-doc
148 --> the new postgres package should work fine with Mir. Make sure you
149 enable UNICODE, and if asked about JDBC (you shouldn't be) make sure
150 to enable it as well. if you would like to try a graphical frontend
151 for the database, find one using
153 apt-cache show postgresql
155 fmailiarize yourself with the psql interface, and the function of the
160 http://java.sun.com/products/java-media/jai/downloads/download.html
162 and download the "CLASSPATH for Linux" version of the JAI package
163 (1.1.01 works fine, later versions have not been tested by me) to
164 /usr/share/tomcat4/common/lib
168 cd /usr/share/tomcat4/common/lib
170 gunzip "name_of_file.tar.gz" (don't use the quotes: replace with the
171 real name of the file you downloaded!)
173 tar -xvf "name_of_file.tar"
175 read the instructions in
176 /usr/share/tomcat4/common/lib/jai_whatever_version_you_have/INSTALL-jai.txt
178 Now add the JAI files to your CLASSPATH and LSD_LIBRARY_PATH:
179 JAIHOME=$TOMCAT_HOME/common/lib/jai-1_1_1_01/lib; export JAIHOME
180 CLASSPATH=$JAIHOME/jai_core.jar:$JAIHOME/jai_codec.jar:$JAIHOME/mlibwrapper_jai.jar:$CLASSPATH;
182 LD_LIBRARY_PATH=.:$JAIHOME:$CLASSPATH; export LD_LIBRARY_PATH
184 --> make sure to replace "jai-1_1_1_01" in the above with the
185 version-number of your copy of JAI
186 --> as above, it's a good idea to add these lines to your .bashrc
188 ---------------------------------------------------------------
193 (a). get the latest version:
195 cd to the directory where you would like to install the mir package
201 cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs login
206 cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs co mir
209 (b) customize the config:
212 cp config.properties-dist config.properties
214 now customize config.properties for your needs. config.properties is
215 pretty well-documented, but read it carefully. I had to recompile
216 several times before I got all the pathnames right.
219 (c) configure the perms.sh file if neccessary -- IMPORTANT! READ THIS!
220 We provide a script that sets all files' and direcories' permissions to
221 a quite reasonable state. This script gets automagically called by
222 ant after compilationl. The most important thing you have to do after
223 compiling Mir is to ensure that the log files -- especially
224 dbentity.log -- are not readable by users that could compromise
225 system security, because all passwords and the like will be logged here.
227 cp perms.sh-dist perms.sh
229 Now, change the install directory and group in perms.sh
234 (d) Customize the templates
235 you need to edit the templates before compiling, or not all of your
236 changes will show up in the produced site. If this is too
237 intimidating, don't worry -- you can always recompile! It only takes
241 --> tomcat 4.1 has a different method of composing servlet URL's, so
242 if you are uasing 4.1, you wil need to make some minor changes to
245 look for sections like this:
255 the url-pattern has to change; so replace the above with:
264 make sure to do the same for OpenMir and OutputMir.
267 -------------------------------------------------------------
268 -------------------------------------------------------------
269 IMPORTANT! It is a good idea to skip ahead to (2) and create the
270 Postgres database at this point. Then cd back to the mir directory,
272 -------------------------------------------------------------
273 -------------------------------------------------------------
275 (f) compile. Make sure all the environment variables are set as
276 indicated in section (0), or build.xml will not run properly:
281 This should take about a minute. If you don't get an error, run
286 Do this as root so the permissions script is able to set
287 the permissions and owners correctly.
290 (g) Get Tomcat to recognize Mir.
291 Link in the webapps directory of tomcat to the install directory
292 (unless you changed the setting in config.properties, the
293 directory is called "Mir" and is located in the same directory in which
294 you installed the "mir" directory). (Here and in the rest of this document,
295 we assume you called the link "Mir", but this could be named anything.)
296 cd /path/to/tomcat/webapps (tomcat-4.0.x/webapps)
297 ln -s /path/to/Mir Mir
299 dynamically reload Mir:
301 http://localhost:8180/manager/stop?path=/Mir
302 if you're not using the Debian installation, you need to use:
303 http://localhost:8080/manager/stop?path=/Mir
305 if you're using Tomcat 3.3, you need to restart Tomcat (consult the
306 docs for how to do that).
309 (h) Copy any dynamic library files ending with ".so" (so far only the JAI native
310 acceleration library found in the JAI package tarball or zip from sun) to your
311 $JAVA_HOME/jre/lib/i386 directory (where the other ".so" files live). Or, you
312 can skip the whole thing and live without "native" acceleration for image
315 (2) CREATE AND CONLFIGURE THE MIR DATABASE!
317 Review mir/etc/config.properties. Look carefully at the entries you
318 put in the DATABASE SETUP section, especially the Username, Password,
319 Host, and Name variables. If you don't know anything about Postgres,
320 look over the INSTALL.postgresql document, which is very helpful (but
321 remember, you don't need to install postgresql from scratch
322 anymore if you're on Debian woody!). Please do not use the "postgres"
323 user in config.properties -- this is a serious security risk. Choose
324 a username,a password, and a database name, then put those values in
325 config.properties if you haven't already.
327 (a) Create the new database
329 We create and configure the database as posgresql user "postgres":
331 createdb -U postgres --encoding=unicode Mir
332 --> here and elsewhere, replace "Mir" with the name you already chose
336 (b) create an unprivileged database user for Mir
337 First, connect to the database as the database's superuser.
341 Now we create the actual user. Please choose a password that is hard to
342 guess instead of "joshua". Good passwords have characters and numerals in
343 it, have no link to its owner (like being her birthday, age, name of her
344 husband, dog, child, car, favourite beer brand). A good password looks like
347 CREATE USER Mir WITH PASSWORD 'joshua' NOCREATEDB NOCREATEUSER;
348 --> again, don't just copy this into the psql command line -- replace
349 "Mir" and "joshua" with your username and password from config.properties
355 (c) create base table
356 cd back to the mir home directory. now execute the following:
358 psql -Upostgres -f dbscripts/create_pg.sql Mir
361 back in the shell, execute the dbscripts:
362 for i in dbscripts/help*.sql ; do psql -Upostgres -f $i Mir ; done
363 for i in dbscripts/populate*.sql ; do psql -Upostgres -f $i Mir ; done
365 (d) Grant the required permissions to the new user
366 First, make your new user into the database administrator for the new
367 database (instead of postgres):
369 select * from pg_database;
370 select * from pg_user;
371 you'll see a display like this:
372 usename | usesysid | usecreatedb | usetrace | usesuper | usecatupd | passwd | valuntil
373 --------------+----------+-------------+----------+----------+-----------+----------+----------
374 postgres | 1 | t | t | t | t | ******** |
375 matt | 100 | t | f | t | t | ******** |
376 mir | 101 | f | f | f | f | ******** |
380 datname | datdba | encoding | datistemplate | datallowconn | datlastsysoid | datvacuumxid | datfrozenxid | datpath
381 -----------+--------+----------+---------------+--------------+---------------+--------------+--------------+---------
383 template1 | 1 | 5 | t | t | 16554 | 11258 | 3221236731 |
385 template0 | 1 | 5 | t | f | 16554 | 49 | 49 |
387 Mir | 1 | 5 | f | t | 16554 | 10805 | 3221236278 |
389 note the "usesysid" column for your new user, and the datname for your
390 new database. now execute the following line, obviousjly using the
391 variable you just noted:
393 update pg_database set datdba=USESYSID_FROM_PG_USER where datname=DATABASENAME
398 save the following lines to a file called set.permissions:
400 select 'grant all on '||relname||' to Mir;'
402 where relname not like 'pg%'
405 -->be sure to replace "Mir" with your username!!!
407 (e) Apply neccessary changes to config.properties
409 --> if you folowed the instructions above, you shouldn't have to do
410 this, but doublecheck!
411 Please open config.properties and look for the lines that begin with
412 "Database.". The interesting properties are "Username", "Password", "Host"
413 and "Name". Change these properties so that they reflect the settings you
414 used to create the database and the user.
416 You should make sure that no copy of config.properties (neither in mir nor
417 in Mir/src nor in Mir/WEB-INF/classes nor in the directory tree you compiled
418 Mir from) is world-readable. Else you wouldn't have to install a password,
421 (f) Setup PostgreSQL so that all connections have to pass a password
423 In /etc/postgresql/pg_hba.conf you should make sure that nobody can
424 use the database without a password, by inserting these lines:
427 host all 127.0.0.1 255.0.0.0 password
428 host all 0.0.0.0 0.0.0.0 reject
430 make sure you comment out all other permissions lines in this file!
432 This means: All local connections (i.e. psql without "-h hostname" option)
433 have to authenticate themselves with a password. All connections from
434 localhost (127.0.0.1) have to supply a password, too. All other connections
435 are rejected. This line doen't have to be there if you have a properly
436 configured firewall but even if you do have one, it adds to the security in
437 case an attacker penetrates the firewall by some hack.
439 If you can't access PostgreSQL after this for any reason, try and change
440 "password" in /etc/postgresql/pg_hba.conf to "trust". This should disable
441 any authentication method and make the database accessible again. Please use
442 this setting only temporarily because anybody who can access the PostgreSQL
443 server could take over the database completely this way. After you fixed
444 your password setting, switch the setting back to "password".
445 You may want to change your PostgreSQL password from time to time to make
446 database takeover harder. Rememer: Security is a process.
448 ----------------------------------------------------------------
450 AT THIS POINT YOU SHOULD HAVE A WORKING INSTAATION OF MIR! CHECK TO
451 MAKE SURE -- DON'T BOTHER WITH THE REST TILL YOIU'VE MADE MIR WORK ONCE!
456 (3) Add the dupe prevention trigger to the database:
457 cd mir/dbscripts/dupetrigger
459 There, read INSTALL and follow the instructions.
462 (4) Tweak mime-type extensions mappings in etc/web.xml file.
464 *** Note the defaults should be o.k for most installations ***
466 Add or remove any mime types you wish to support. This is used to figure
467 out the mime-type when (broken browsers?) browsers don't send the mime-type
468 in the content-type header field when uploading a media file. Note add the
469 moment you still have to add these to the media_type SQL table as well which
470 maps the mime-types to the correct mediaHandler class. See the comments in
471 the MirMedia class in javadoc for more details.
478 * set the document root to the same directory as in the mir config file
479 * enable shtml includes:
480 - add LoadModule includes_module /usr/lib/apache/1.3/mod_include.so
481 - make sure your directory contains "Options Includes"
482 * Determine if you need to modify any apache mime-mappings
483 - The web-server host must recognize the .m3u, .pls and other file extensions
484 and send the proper "audio/x-mpegurl" and "audio/x-scpls" mime-types
485 respectively. If the web server is apache, it's easy, just
491 to the file pointed to by the "TypesConfig" command in your apache config
492 file. Or add and equivalent AddType command to your httpd.conf. Of course
493 this assumes that the mod_mime is loaded.
497 now the admin-application is accesable via:
499 http://host/Mir/servlet/Mir
501 and the openposting-servlet via
503 http://host/Mir/servlet/OpenMir
505 standard login is admin/indymedia. See the webdb_users SQL table to change/add
511 The Mir code offers no internal search facilities, rather, the design
512 expects the use of an external program to crawl and index the static
513 site. One (recommended) tool for doing this is htdig
514 (http://htdig.org), which generates static databases of the site
515 content and then accesses those databases through a very fast CGI
516 program written in C. In the scripts directory, a perl CGI script
517 which wraps calls to htsearch is provided (scripts/search.pl) which
518 will allow searching based off of media type. (This is possible
519 because the standard templates will include META keywords like
520 hasAudio, hasVideo, etc.)
524 see the UPGRADING.mir file.
528 You can give these a try if anything goes wrong:
530 + Restart Tomcat. Especially after compiling the sources Tomcat has to be
533 + Check file permissions and ownership. Try and run perms.sh.
535 ----------------------------------------------------------------
537 $Date: 2003/01/18 08:44:09 $ - the Mir coders