X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2FINSTALL.mir;h=d011c7b0f9ed03c8f9d627adbbe91e65b4aec644;hb=3c364f8a2958d05e0e0f5badd4a82f52c4e6501b;hp=989d14cc3ebffb8fb26835d5a4524224a63644ec;hpb=d629d9481e10ee8b835fa8858a9b85ccb1db58f9;p=mir.git diff --git a/doc/INSTALL.mir b/doc/INSTALL.mir index 989d14cc..d011c7b0 100755 --- a/doc/INSTALL.mir +++ b/doc/INSTALL.mir @@ -1,90 +1,182 @@ +MIR INSTALLATION HOWTO + +Last updated: $Date: 2003/11/24 19:57:54 $ +---------------------------------------------------------------- + Here is a short installation-howto of Mir. prerequisites: -- tomcat -- apache with mod_jk.so -- postgres 7.1.x +- tomcat 4.0.4+ or 3.3 (4.0.3 and below have some bad bugs) + tomcat is available from http://jakarta.apache.org/tomcat/ +- apache 1.3.x. with mod_jk.so. As far as I can tell the connector for 2.x is + still rather undocumented. http://httpd.apache.org +- postgres 7.1+ - 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/common/lib) directory and + not under the default webapps/Mir/WEB-INF/lib directory ** +- A good reading of Tomcat, Apache and Postgresql documentation if you are not + familiar with any of them. The documentation is available at: + http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html, + http://httpd.apache.org/docs/ and http://www.postgresql.org respectively. 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/cvs co -r MIR_1_1 mir 2. customize the config: - cd mir/source + cd mir/etc cp config.properties-dist config.properties now customize config.properties for your needs. -3. configure the build.sh file with java_home - cp build.sh-dist build.sh - chmod 755 build.sh +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 + + edit perms.sh +4. There is NO step 4!! -4. copy the mir/template-dist-directory to mir/template +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. +Do this as root so the permissions script is able to set +the permissions and owners correctly. -5. compile - sh build.sh + ant 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 - ln -s Mir-install-dir Mir +directory is in mir/bin/mir (Here and in the rest of this document, +we assume you called the link "Mir", but this could be named anything.) + cd ${TOMCAT_HOME}/webapps + ln -s /path/to/mir/bin/mir Mir + +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: + +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. + +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. + +It is wise in terms of system security 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 "joe" 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. In the +following example we'll create the mir database as postgreSQL user +"pete". + + cd mir/dbscripts + su postgres + ./createmirdb.sh mir pete joe joshua + +8b. Apply neccessary changes to config.properties + +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. + +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. +8c. Setup PostgreSQL so that all localhost connections have to pass a +password -7. create a new database -the database name should be the same as in config.properties -as user postgres: - createdb dbname +In /etc/postgresql/pg_hba.conf, change the line with 127.0.0.1 as follows: +host all 127.0.0.1 255.0.0.0 password -8. create base table - psql -Upostgres dbname < dbscripts/create_pg.sql - cat dbscript/help*.sql | psql -Upostgres dbname - cat dbscript/populate*.sql | psql -Upostgres dbname +This means: All connections from 127.0.0.1 to any database will have to +authenticate themselves with a password. Please refer to the PostgreSQL +documentation if you want a different authentication setup. Make sure +however that mir can connect to it's database using password authentication. -9. Add the dupe prevention trigger to the database: - cd dbscripts/dupetrigger - - There, read INSTALL and follow the instructions. - +9. For now, there's no step 9 either. -10. Set permissions - We provide a script that sets all files' and direcories' permissions to - a quite reasonable state. - - cp perms.sh-dist perms.sh - # Now, change the install directory and group in perms.sh - edit perms.sh - ./perms.sh +10. Tweak mime-type extensions mappings in etc/web.xml file. + +*** Note the defaults should be o.k for most installations *** +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. 11. restart tomcat 12. configure mod_jk +There are 2 ways to do this. auto-generation of mod_jk.conf or manula JKMount +lines. (rumour has it that Tomcat 4.0.x doesn't support auto-generation, but +this is unconfirmed). + +In both examples please note that the JkWorkersFile line only needs to appear +once per Apache config. + +Also this assumes that your tomcat installation has it's ajp13 conenctor +turned on. See tomcat's server.xml file and documentation for this. Chances +are that it is turned on. + +Method a). The automatic mod_jk.conf method: + insert the following patch into /etc/apache/httpd.conf. Edit the directories to suit your needs. -JkWorkersFile /usr/share/tomcat/conf/workers.properties -Include /usr/share/tomcat/conf/mod_jk.conf-auto +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! @@ -92,44 +184,80 @@ 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. +Method b). Manual JKMount lines -13. Add a password to your PostgreSQL user and link it to Mir (optional) +insert the following patch into /etc/apache/httpd.conf. Edit the directories +to suit your needs. -Add a hard to guess password to the PostgreSQL user database: + +JkWorkersFile /path/to/tomcat/conf/workers.properties +JkMount /Mir ajp13 +JkMount /Mir/* ajp13 + -# psql -U postgres Mir -alter user postgres with password 'yourpassword'; +13. configure apache for the static site + +* Make sure that if you are using a non standard character set enconding that + Apache doesn't accidentally send the wrong encoding in the HTTP headers. +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" +* Determine if you need to modify any apache mime-mappings + - The web-server host must recognize the .m3u, .pls and other file extensions + and send the proper "audio/x-mpegurl" and "audio/x-scpls" mime-types + respectively. If the web server is apache, it's easy, just + add: + + audio/x-mpegurl m3u + audio/x-scpl pls + + to the file pointed to by the "TypesConfig" command in your apache config + file. Or add and equivalent AddType command to your httpd.conf. Of course + this assumes that the mod_mime is loaded. -Then, in /etc/postgresql/pg_hba.conf you should make sure that nobody can -use the database without a password: +that's it :) -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 +now the admin-application is accesable via: + http://host/Mir/servlet/Mir -Then, change the database password line in config.properties: +and the openposting-servlet via + + http://host/Mir/servlet/OpenMir -Database.Username=postgres -Database.Password=yourpassword +standard login is admin/indymedia. See the webdb_users SQL table to change/add +users or passwords. -You should make sure that no copy of config.properties (neither in mir nor -in Mir/src nor in Mir/WEB-INF/classes) is world-readable. Else you wouldn't -have to install a password, anyway. -If you can't access PostgreSQL after this for any reason, try to change -"password" in /etc/postgresql/pg_hba.conf into "trust". This should disable -any authentication method and make the database accessible again. +SEARCHING -that's it :) +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.) -now the admin-application is accesable via: +UPGRADING - http://host/Mir +see the UPGRADING.mir file. -and the openposting-servlet via - - http://host/OpenMir +TROUBLESHOOTING + +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. + +---------------------------------------------------------------- -standard login is redaktion/indymedia +$Date: 2003/11/24 19:57:54 $ - the Mir coders