X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2FINSTALL.mir;h=bdb61cdade05e51fba5ce926c4e151d00637aa79;hb=e94b3cbaf153a7fba637971e3d0d8d92becbf643;hp=4e255adcb3ad522f05000db70c0d40a9f894f9dc;hpb=baf56cc3d324ffa8715509e559bbe049739f32f3;p=mir.git
diff --git a/doc/INSTALL.mir b/doc/INSTALL.mir
index 4e255adc..bdb61cda 100755
--- a/doc/INSTALL.mir
+++ b/doc/INSTALL.mir
@@ -1,24 +1,40 @@
+MIR INSTALLATION HOWTO
+
+Last updated: $Date: 2002/07/08 16:20:32 $
+----------------------------------------------------------------
+
Here is a short installation-howto of Mir.
prerequisites:
-- tomcat
-- apache with mod_jk.so
-- postgres 7.1.x
+- tomcat 4.0.4 (4.0.3 and below have some bad bugs) or above (3.3 works too as
+ of 04.04.2002, but this could change)
+ 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.x or 7.2.x. http://www.postgresql.org
- 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 **
+- 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 mir
2. customize the config:
@@ -28,84 +44,202 @@ CVS CHECKOUT:
now customize config.properties for your needs.
- modify etc/web.xml to change the xml-config
- parameter to point to where your server.xml file is
- (in ../Mir i.e /path/to/Mir/server.xml)
+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
-3. configure the build.sh file with java_home
- cp build.sh-dist build.sh
- chmod 755 build.sh
+ edit perms.sh
4. copy the mir/templates-dist-directory to mir/templates
-5. compile
- sh build.sh
+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.
+
+ 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
+you installed the "mir" directory). (Here and in the rest of this document,
+we assume you called the link "Mir", but this could be named anything.)
+ cd /path/to/tomcat/webapps (tomcat-4.0.x/webapps)
+ ln -s /path/to/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 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"):
+
+ createdb -U postgres --encoding=unicode Mir
+
+Please note that if you create the database from inside the psql application,
+the database name will likely be converted to lowercase letters.
+
+
+8b. create an unprivileged database user for Mir
+First, connect to the database as the database's superuser.
+
+ psql -U postgres Mir
+
+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
+
+8d. Grant the required permissions to the new user
+
+-- The following should be executed as the "postgres" DB user.
+-- Note that ID_FROM_PG_USER and DATABASENAME should be replace with the
+ appropriate field values from the 2 prior selects.
+-- set owner of datbase
+select * from pg_database;
+select * from pg_user;
+update pg_database set datdba=ID_FROM_PG_USER where datname=DATABASENAME
+
+-- find all tables to grant privs / select is just building sql
+-- to be exectued
+
+select 'grant all on '||relname||' to "de_indy";'
+from pg_class
+where relname not like 'pg%'
+order by relname;
+
+8e. 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.
+
+8f. Setup PostgreSQL so that all connections have to pass a password
-7. 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
+In /etc/postgresql/pg_hba.conf you should make sure that nobody can
+use the database without a password:
-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
+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
+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.
-8. create a new database
-the database name should be the same as in config.properties
-as user postgres:
- createdb dbname
+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
+any authentication method and make the database accessible again. Please use
+this setting only temporarily because anybody who can access the PostgreSQL
+server could take over the database completely this way. After you fixed
+your password setting, switch the setting back to "password".
+You may want to change your PostgreSQL password from time to time to make
+database takeover harder. Rememer: Security is a process.
-9. create base table
- psql -Upostgres dbname < dbscripts/create_pg.sql
- cat dbscripts/help*.sql | psql -Upostgres dbname
- cat dbscripts/populate*.sql | psql -Upostgres dbname
-10. Add the dupe prevention trigger to the database:
+9. Add the dupe prevention trigger to the database:
cd dbscripts/dupetrigger
There, read INSTALL and follow the instructions.
-11. Set permissions
- We provide a script that sets all files' and direcories' permissions to
- a quite reasonable state. The most important thing you have to do after
- the invokation of this script 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
- ./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).
-12. restart tomcat
+In both examples please note that the JkWorkersFile line only needs to appear
+once per Apache config.
-13. configure mod_jk
+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!
@@ -113,59 +247,78 @@ 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
-14. 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
+
+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.
-
-15. configure apache's mod_mime to recognize .m3u and .pls files:
-
-The web server (of the media host) must recognize the .m3u and .pls 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.
- *
-If the web server is not apache, then your on your own.
-that's it :)
+SEARCHING
-now the admin-application is accesable via:
+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.)
- http://host/Mir
+UPGRADING
-and the openposting-servlet via
-
- http://host/OpenMir
+see the UPGRADING.mir file.
+
+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: 2002/07/08 16:20:32 $ - the Mir coders