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