doc/INSTALL.mir

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