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