X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2FINSTALL.mir;h=190efc9a3478205f771bbc05ba372cb8ee17726e;hb=238254c1b04d15d5fb641311f80324433e9908c1;hp=c419c2d795d8d59d303932790600e26583b3f26b;hpb=22724c9a628f102f22310cd972508a86a25bd231;p=mir.git diff --git a/doc/INSTALL.mir b/doc/INSTALL.mir index c419c2d7..190efc9a 100755 --- a/doc/INSTALL.mir +++ b/doc/INSTALL.mir @@ -1,24 +1,32 @@ +MIR INSTALLATION HOWTO +---------------------------------------------------------------- + Here is a short installation-howto of Mir. prerequisites: -- tomcat -- apache with mod_jk.so -- postgres 7.1.x +- tomcat 4.0.3 or above (3.3 works too as of 04.04.2002, but this could change) + tomcat is available from http://jakarta.apache.org +- apache with mod_jk.so +- postgres 7.1.x or 7.2.x - ant (a java-based make) - jaxp-1.1 (a SAX 2.0 compliant XML parser, comes with ant >= 1.4) +- the JAI image framework (Java Advanced Imaging) versin 1.1.1 . get it from + java.sun.com. ** NOTE: because JAI uses a native acceration library (a .so) + it must be placed in tomcat's "lib" (i.e $TOMCAT_HOME/lib) directory and + not under the default webapps/Mir/WEB-INF/lib directory ** 1. checkout the cvs CVS LOGIN: - cvs -d :pserver: cvsanon@brazil.indymedia.de:/var/cvs login - password: cvs + cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs login + password: anonymous CVS CHECKOUT: - cvs -d :pserver: cvsanon@brazil.indymedia.de:/var/cvs co mir + cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvsco mir 2. customize the config: @@ -29,112 +37,143 @@ CVS CHECKOUT: now customize config.properties for your needs. -3. configure the build.xml file if neccessary - cd .. - cp build.xml-new build.xml - - -4. configure the perms.sh file if neccessary -- IMPORTANT! READ THIS! - We provide a script that sets all files' and direcories' permissions to - a quite reasonable state. This script gets automagically called by - ant after compilationl. The most important thing you have to do after - compiling Mir is to ensure that the log files -- especially - dbentity.log -- are not readable by users that could compromise - system security, because all passwords and the like will be logged here. +3. configure the perms.sh file if neccessary -- IMPORTANT! READ THIS! +We provide a script that sets all files' and direcories' permissions to +a quite reasonable state. This script gets automagically called by +ant after compilationl. The most important thing you have to do after +compiling Mir is to ensure that the log files -- especially +dbentity.log -- are not readable by users that could compromise +system security, because all passwords and the like will be logged here. cp perms.sh-dist perms.sh - # Now, change the install directory and group in perms.sh + +Now, change the install directory and group in perms.sh + edit perms.sh -5. copy the mir/templates-dist-directory to mir/templates +4. copy the mir/templates-dist-directory to mir/templates + +5. compile. For this step, you have to make sure that the TOMCAT_HOME +environment variable is set to the root of your tomcat installation. +The build.xml compile target will give up if this is not set. -6. compile (do this as root so the permissions script is able to set -the permissions and owners correctly). +Do this as root so the permissions script is able to set +the permissions and owners correctly. ant -7. Link in the webapps directory of tomcat to the install directory (the +6. Link in the webapps directory of tomcat to the install directory (the directory is called "Mir" and is located in the same directory in which you installed the "mir" directory). - cd /usr/share/tomcat/webapps + cd /path/to/tomcat/webapps (tomcat-4.0.x/webapps) ln -s Mir-install-dir Mir -8. Modify your tomcat startup script and add an LD_LIBRARY_PATH variable -that points to the WEB-INF/lib directory of your Mir install dir. (called -"Mir"). Add something like the following at the top of tomcat.sh (tomcat.sh -is found in the "bin/" dir. under $TOMCAT_HOME): - LD_LIBRARY_PATH=/path/to/Mir-install-dir/WEB-INF/lib +with tomcat 4.0.x, you could dynamically reload and stop the Mir webapp without +restarting tomcat by using the "Manager App" with the following url: -An alternaive way to avoid this is to copy any dynamic library files -ending with ".so" in WEB-INF/lib to your jre/jdk lib directory (where the -other ".so" files live). Or, you can skip the whole thing and live without -"native" acceleration for image manipulation +http://localhost:8080/manager/stop?path=/mir +This is practical if you are running several installations of mir on one +tomcat or other webapps and can't afford to shutdown all of them. +See the tomcat documentation to learn how to enable and use the manager app. -9. create a new database -the database name should be the same as in config.properties -as user postgres: - createdb dbname +7. Copy any dynamic library files ending with ".so" (so far only the JAI native +acceleration library found in the JAI package tarball or zip from sun) to your +$JAVA_HOME/jre/lib/i386 directory (where the other ".so" files live). Or, you +can skip the whole thing and live without "native" acceleration for image +manupulation. +8a. create a new database +The database name should be the same as in config.properties. Please look at +the section "Database.*" to look up the names or change them to your needs. -10. create base table - psql -Upostgres dbname < dbscripts/create_pg.sql - cat dbscripts/help*.sql | psql -Upostgres dbname - cat dbscripts/populate*.sql | psql -Upostgres dbname +It is wise in terms of system seurity to use an unprivileged user for this +task instead of the superuser. This is because if Mir uses the superuser to +connect to the database and anybody manages to find out the password Mir +uses to connect, the attacker can take over the complete database. So, in +the following examples, we assume that the database name is "Mir", the +database user will be "mir" and the password is "joshua". Please note that +this particular password is far from being a good one. Watch "Wargames" for +details. =B) +To access the database as the database superuser, you either have to log in +as postgres on Unix level (which we don't recommend because you will need +another user to have a login shell and a password which makes system +penetration more likely) or you have to tell PostgreSQL with each +application call that you want to connect as a specific user. If you access +the database from any other user's account, use the -U flag to connect to +PostgreSQL as the database superuser ("postgres"): -11. Add the dupe prevention trigger to the database: - cd dbscripts/dupetrigger - - There, read INSTALL and follow the instructions. - + createdb -U postgres --encoding=unicode Mir -12. restart tomcat +Please note that if you create the database from inside the psql application, +the database name will likely be converted to lowercase letters. -13. configure mod_jk -insert the following patch into /etc/apache/httpd.conf. Edit the directories -to suit your needs. +8b. create an unprivileged database user for Mir +First, connect to the database as the database's superuser. - -JkWorkersFile /usr/share/tomcat/conf/workers.properties -Include /usr/share/tomcat/conf/mod_jk.conf-auto - + psql -U postgres Mir -Do not put any JkMount lines into your httpd.conf! +Now we create the actual user. Please choose a password that is hard to +guess instead of "joshua". Good passwords have characters and numerals in +it, have no link to its owner (like being her birthday, age, name of her +husband, dog, child, car, favourite beer brand). A good password looks like +this: "8ncx4un". + + CREATE USER Mir WITH PASSWORD 'joshua' NOCREATEDB NOCREATEUSER; + + +8c. create base table +Please note that we use the superuser "postgres" to connect to the "Mir" +database, /not/ the user "mir". + + psql -Upostgres -f dbscripts/create_pg.sql Mir + for i in dbscripts/help*.sql ; do psql -Upostgres -f $i Mir ; done + for i in dbscripts/populate*.sql ; do psql -Upostgres -f $i Mir ; done -If mod_jk.conf-auto doesn't get written or is 0 bytes in size, check your -system for file ownership/permissions problems. +8d. Apply neccessary changes to config.properties -14. Add a password to your PostgreSQL user and link it to Mir (optional) +Please open config.properties and look for the lines that begin with +"Database.". The interesting properties are "Username", "Password", "Host" +and "Name". Change these properties so that they reflect the settings you +used to create the database and the user. -Add a hard to guess password to the PostgreSQL user database: +You should make sure that no copy of config.properties (neither in mir nor +in Mir/src nor in Mir/WEB-INF/classes nor in the directory tree you compiled +Mir from) is world-readable. Else you wouldn't have to install a password, +anyway. -# psql -U postgres Mir -alter user postgres with password 'yourpassword'; +8e. Tweak mime-type extensions mappings in etc/web.xml file. +*** Note the defaults should be o.k for most installations *** -Then, in /etc/postgresql/pg_hba.conf you should make sure that nobody can +Add or remove any mime types you wish to support. This is used to figure +out the mime-type when (broken browsers?) browsers don't send the mime-type +in the content-type header field when uploading a media file. Note add the +moment you still have to add these to the media_type SQL table as well which +maps the mime-types to the correct mediaHandler class. See the comments in +the MirMedia class in javadoc for more details. + +8f. Setup PostgreSQL so that all connections have to pass a password + +In /etc/postgresql/pg_hba.conf you should make sure that nobody can use the database without a password: local all password host all 127.0.0.1 255.0.0.0 password host all 0.0.0.0 0.0.0.0 reject - -Then, change the database password line in config.properties: - -Database.Username=postgres -Database.Password=yourpassword - -You should make sure that no copy of config.properties (neither in mir nor -in Mir/src nor in Mir/WEB-INF/classes nor in the directory tree you compiled -Mir from) is world-readable. Else you wouldn't have to install a password, -anyway. +This means: All local connections (i.e. psql without "-h hostname" option) +have to authenticate themselves with a password. All connections from +localhost (127.0.0.1) have to supply a password, too. All other connections +are rejected. This line doen't have to be there if you have a properly +configured firewall but even if you do have one, it adds to the security in +case an attacker penetrates the firewall by some hack. If you can't access PostgreSQL after this for any reason, try and change "password" in /etc/postgresql/pg_hba.conf to "trust". This should disable @@ -146,6 +185,40 @@ You may want to change your PostgreSQL password from time to time to make database takeover harder. Rememer: Security is a process. + +9. Add the dupe prevention trigger to the database: + cd dbscripts/dupetrigger + + There, read INSTALL and follow the instructions. + + +10. restart tomcat + +11. configure mod_jk + +insert the following patch into /etc/apache/httpd.conf. Edit the directories +to suit your needs. + + +JkWorkersFile /path/to/tomcat/conf/workers.properties +Include /path/to/tomcat/conf/mod_jk.conf-auto + + +Do not put any JkMount lines into your httpd.conf! + +If mod_jk.conf-auto doesn't get written or is 0 bytes in size, check your +system for file ownership/permissions problems. + + +12. configure apache + +edit http.conf: +* set the document root to the same directory as in the mir config file +* enable shtml includes: + - add LoadModule includes_module /usr/lib/apache/1.3/mod_include.so + - make sure your directory contains "Options Includes" + + that's it :) now the admin-application is accesable via: @@ -159,6 +232,22 @@ and the openposting-servlet via standard login is redaktion/indymedia +SEARCHING + +The Mir code offers no internal search facilities, rather, the design +expects the use of an external program to crawl and index the static +site. One (recommended) tool for doing this is htdig +(http://htdig.org), which generates static databases of the site +content and then accesses those databases through a very fast CGI +program written in C. In the scripts directory, a perl CGI script +which wraps calls to htsearch is provided (scripts/search.pl) which +will allow searching based off of media type. (This is possible +because the standard templates will include META keywords like +hasAudio, hasVideo, etc.) + +UPGRADING + +see the UPGRADING.mir file. TROUBLESHOOTING @@ -167,4 +256,8 @@ You can give these a try if anything goes wrong: + Restart Tomcat. Especially after compiling the sources Tomcat has to be restarted. -+ Check file permissions and ownership. Try and run perms.sh. \ No newline at end of file ++ Check file permissions and ownership. Try and run perms.sh. + +---------------------------------------------------------------- + +2001, 2002 - the Mir coders