note about using jikes

[mir.git] / doc / INSTALL.mir

MIR INSTALLATION HOWTO

Last updated: $Date: 2002/10/12 11:22:03 $
----------------------------------------------------------------

Here is a short installation-howto of Mir.


prerequisites: 

- 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/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:anonymous@mir.indymedia.org:/var/lib/cvs login
        password: anonymous

CVS CHECKOUT:

        cvs -d :pserver:anonymous@mir.indymedia.org:/var/lib/cvs co mir 


2. customize the config: 

        cd mir/etc
        cp config.properties-dist config.properties 

now customize config.properties for your needs.


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. 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.

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). (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

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

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
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. Add the dupe prevention trigger to the database:
        cd dbscripts/dupetrigger
        
        There, read INSTALL and follow the instructions.
        

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.

<IfModule mod_jk.c>
JkWorkersFile /path/to/tomcat/conf/workers.properties
Include /path/to/tomcat/conf/mod_jk.conf-auto
</IfModule>

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

insert the following patch into /etc/apache/httpd.conf. Edit the directories
to suit your needs.

<IfModule mod_jk.c>
JkWorkersFile /path/to/tomcat/conf/workers.properties
JkMount /Mir ajp13
JkMount /Mir/* ajp13
</IfModule>


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.

that's it :)

now the admin-application is accesable via:  

        http://host/Mir/servlet/Mir 

and the openposting-servlet via  
        
        http://host/Mir/servlet/OpenMir

standard login is admin/indymedia. See the webdb_users SQL table to change/add
users or passwords.


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

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.

----------------------------------------------------------------

$Date: 2002/10/12 11:22:03 $ - the Mir coders