doc/INSTALL.mir

   1 MIR INSTALLATION HOWTO
   2
   3 Last updated: $Date: 2003/11/24 19:57:54 $
   4 ----------------------------------------------------------------
   5
   6 Here is a short installation-howto of Mir.
   7
   8
   9 prerequisites:
  10
  11 - tomcat 4.0.4+ or 3.3 (4.0.3 and below have some bad bugs)
  12   tomcat is available from http://jakarta.apache.org/tomcat/
  13 - apache 1.3.x. with mod_jk.so. As far as I can tell the connector for 2.x is
  14   still rather undocumented. http://httpd.apache.org
  15 - postgres 7.1+
  16 - ant (a java-based make)
  17 - jaxp-1.1 (a SAX 2.0 compliant XML parser, comes with ant >= 1.4)
  18 - the JAI image framework (Java Advanced Imaging) versin 1.1.1 . get it from
  19   java.sun.com. ** NOTE: because JAI uses a native acceration library (a .so)
  20   it must be placed in tomcat's "lib" (i.e $TOMCAT_HOME/common/lib) directory and
  21   not under the default webapps/Mir/WEB-INF/lib directory **
  22 - A good reading of Tomcat, Apache and Postgresql documentation if you are not
  23   familiar with any of them. The documentation is available at:
  24   http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html,
  25   http://httpd.apache.org/docs/ and http://www.postgresql.org respectively.
  26
  27 1. checkout the cvs
  28
  29 CVS LOGIN:
  30
  31   cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs login
  32         password: anonymous
  33
  34 CVS CHECKOUT:
  35
  36         cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs co -r MIR_1_1 mir
  37
  38
  39 2. customize the config:
  40
  41         cd mir/etc
  42         cp config.properties-dist config.properties
  43
  44 now customize config.properties for your needs.
  45
  46
  47 3. configure the perms.sh file if neccessary -- IMPORTANT! READ THIS!
  48 We provide a script that sets all files' and direcories' permissions to
  49 a quite reasonable state. This script gets automagically called by
  50 ant after compilationl. The most important thing you have to do after
  51 compiling Mir is to ensure that the log files -- especially
  52 dbentity.log -- are not readable by users that could compromise
  53 system security, because all passwords and the like will be logged here.
  54
  55         cp perms.sh-dist perms.sh
  56
  57 Now, change the install directory and group in perms.sh
  58
  59         edit perms.sh
  60
  61 4. There is NO step 4!!
  62
  63 5. compile. For this step, you have to make sure that the TOMCAT_HOME
  64 environment variable is set to the root of your tomcat installation.
  65 The build.xml compile target will give up if this is not set.
  66
  67 Do this as root so the permissions script is able to set
  68 the permissions and owners correctly.
  69
  70     ant
  71
  72
  73 6. Link in the webapps directory of tomcat to the install directory (the
  74 directory is in mir/bin/mir (Here and in the rest of this document,
  75 we assume you called the link "Mir", but this could be named anything.)
  76         cd ${TOMCAT_HOME}/webapps
  77         ln -s /path/to/mir/bin/mir Mir
  78
  79 with tomcat 4.0.x, you could dynamically reload and stop the Mir webapp without
  80 restarting tomcat by using the "Manager App" with the following url:
  81
  82 http://localhost:8080/manager/stop?path=/Mir
  83
  84 This is practical if you are running several installations of mir on one
  85 tomcat or other webapps and can't afford to shutdown all of them.
  86 See the tomcat documentation to learn how to enable and use the manager app.
  87
  88 7. Copy any dynamic library files ending with ".so" (so far only the JAI native
  89 acceleration library found in the JAI package tarball or zip from sun) to your
  90 $JAVA_HOME/jre/lib/i386 directory (where the other ".so" files live). Or, you
  91 can skip the whole thing and live without "native" acceleration for image
  92 manupulation.
  93
  94 8a. create a new database
  95 The database name should be the same as in config.properties. Please look at
  96 the section "Database.*" to look up the names or change them to your needs.
  97
  98 It is wise in terms of system security to use an unprivileged user for this
  99 task instead of the superuser. This is because if Mir uses the superuser to
 100 connect to the database and anybody manages to find out the password Mir
 101 uses to connect, the attacker can take over the complete database. So, in
 102 the following examples, we assume that the database name is "Mir", the
 103 database user will be "joe" and the password is "joshua". Please note that
 104 this particular password is far from being a good one. Watch "Wargames" for
 105 details. =B)
 106
 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. In the
 113 following example we'll create the mir database as postgreSQL user
 114 "pete".
 115
 116         cd mir/dbscripts
 117         su postgres
 118         ./createmirdb.sh mir pete joe joshua
 119
 120 8b. Apply neccessary changes to config.properties
 121
 122 Please open config.properties and look for the lines that begin with
 123 "Database.". The interesting properties are "Username", "Password", "Host"
 124 and "Name". Change these properties so that they reflect the settings you
 125 used to create the database and the user.
 126
 127 You should make sure that no copy of config.properties (neither in mir nor
 128 in Mir/src nor in Mir/WEB-INF/classes nor in the directory tree you compiled
 129 Mir from) is world-readable. Else you wouldn't have to install a password,
 130 anyway.
 131
 132 8c. Setup PostgreSQL so that all localhost connections have to pass a
 133 password
 134
 135 In /etc/postgresql/pg_hba.conf, change the line with 127.0.0.1 as follows:
 136
 137 host         all         127.0.0.1     255.0.0.0           password
 138
 139 This means: All connections from 127.0.0.1 to any database will have to
 140 authenticate themselves with a password. Please refer to the PostgreSQL
 141 documentation if you want a different authentication setup. Make sure
 142 however that mir can connect to it's database using password authentication.
 143
 144 9. For now, there's no step 9 either.
 145
 146 10. Tweak mime-type extensions mappings in etc/web.xml file.
 147
 148 *** Note the defaults should be o.k for most installations ***
 149
 150 Add or remove any mime types you wish to support. This is used to figure
 151 out the mime-type when (broken browsers?) browsers don't send the mime-type
 152 in the content-type header field when uploading a media file. Note add the
 153 moment you still have to add these to the media_type SQL table as well which
 154 maps the mime-types to the correct mediaHandler class. See the comments in
 155 the MirMedia class in javadoc for more details.
 156
 157 11. restart tomcat
 158
 159 12. configure mod_jk
 160
 161 There are 2 ways to do this. auto-generation of mod_jk.conf or manula JKMount
 162 lines. (rumour has it that Tomcat 4.0.x doesn't support auto-generation, but
 163 this is unconfirmed).
 164
 165 In both examples please note that the JkWorkersFile line only needs to appear
 166 once per Apache config.
 167
 168 Also this assumes that your tomcat installation has it's ajp13 conenctor
 169 turned on. See tomcat's server.xml file and documentation for this. Chances
 170 are that it is turned on.
 171
 172 Method a). The automatic mod_jk.conf method:
 173
 174 insert the following patch into /etc/apache/httpd.conf. Edit the directories
 175 to suit your needs.
 176
 177 <IfModule mod_jk.c>
 178 JkWorkersFile /path/to/tomcat/conf/workers.properties
 179 Include /path/to/tomcat/conf/mod_jk.conf-auto
 180 </IfModule>
 181
 182 Do not put any JkMount lines into your httpd.conf!
 183
 184 If mod_jk.conf-auto doesn't get written or is 0 bytes in size, check your
 185 system for file ownership/permissions problems.
 186
 187 Method b). Manual JKMount lines
 188
 189 insert the following patch into /etc/apache/httpd.conf. Edit the directories
 190 to suit your needs.
 191
 192 <IfModule mod_jk.c>
 193 JkWorkersFile /path/to/tomcat/conf/workers.properties
 194 JkMount /Mir ajp13
 195 JkMount /Mir/* ajp13
 196 </IfModule>
 197
 198
 199 13. configure apache for the static site
 200
 201 * Make sure that if you are using a non standard character set enconding that
 202   Apache doesn't accidentally send the wrong encoding in the HTTP headers.
 203 edit http.conf:
 204 * set the document root to the same directory as in the mir config file
 205 * enable shtml includes:
 206   - add LoadModule includes_module /usr/lib/apache/1.3/mod_include.so
 207   - make sure your directory contains "Options Includes"
 208 * Determine if you need to modify any apache mime-mappings
 209   - The web-server host must recognize the .m3u, .pls and other file extensions
 210     and send the proper "audio/x-mpegurl" and "audio/x-scpls" mime-types
 211     respectively.  If the web server is apache, it's easy, just
 212     add:
 213
 214     audio/x-mpegurl                 m3u
 215     audio/x-scpl                    pls
 216
 217     to the file pointed to by the "TypesConfig" command in your apache config
 218     file. Or add and equivalent AddType command to your httpd.conf.  Of course
 219     this assumes that the mod_mime is loaded.
 220
 221 that's it :)
 222
 223 now the admin-application is accesable via:
 224
 225         http://host/Mir/servlet/Mir
 226
 227 and the openposting-servlet via
 228
 229         http://host/Mir/servlet/OpenMir
 230
 231 standard login is admin/indymedia. See the webdb_users SQL table to change/add
 232 users or passwords.
 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 $Date: 2003/11/24 19:57:54 $ - the Mir coders