quickly mention blurb about apache and character encoding

[mir.git] / doc / LONG.INSTALL.mir

MIR INSTALLATION HOWTO

Last updated: $Date: 2003/01/18 08:44:09 $
----------------------------------------------------------------

Here is a short installation-howto of Mir, somewhat more explicit than
the earlier version.  Some Debian-specific instructions are given.  


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.
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
0. To set all this up on Debian:

make sure you have stable, testing, and unstable listings in
/etc/apt/sources.list.  THen do all the following as root or using sudo!

If you already have tomcat, and it's working well with apache, then
skip directly to (c).  If it's not working well, then make sure you
purge _all_ conf files & so forth ( though it never hurts to back them
up first).  "apt-get remove --purge" may not get rid of everything; try 

locate tomcat
and then delete all the files you find (again, if you're unsure what
they are, then back them up first).


(a) Install Java 
apt-get install j2sdk1.3 j2sdk1.3-doc

JAVA_HOME=/usr/lib/j2sdk1.3; export JAVA_HOME
PATH=$PATH:$JAVA_HOME/bin; export PATH
(add these lines to your .bashrc as well)

(b) Installing Tomcat and Apache

As root, do the following:
apt-get install apache 
 configure apache by editing httpd.conf:
* 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.
* 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.



Now deal with Tomcat:
apt-get install -t unstable tomcat4 tomcat4-webapps tomcat4-admin 
        --> this gets you tomcat4.1.  You can work with tomcat 4.0.4
        as well, but a couple of specific configuration elements are
        different.  To get 4.0.4, run the following:
        apt-get install -t testing tomcat4 tomcat4-webapps
apt-get install apachelib-java

Tomcat will be installed in /usr/share/tomcat4, so you should put 

CATALINA_HOME=/usr/share/tomcat4; export CATALINA_HOME
TOMCAT_HOME=$CATALINA_HOME; export TOMCAT_HOME

in your .bashrc; you might as well execute the ocmmand right now as
well.  

I found it somewhat difficult to get Tomcat and Apache working
   together, until I emailed the Debian package maintainer, who told
   me that he had purposely removed the mod_jk.conf-auto function from
   Tomcat4.1!  This is because Debian encourages Tomcat users to
   switch to mod_webapp instead.  You may want to try this option
   out.  I didn't, because I was able to get it working using the
   JkMount option.  So in /etc/apache/httpd.conf, look for a section
   like this at the end:  
        <IfModule mod_jk.c>                                                           
        # The following line is for apacheconfig - DO NOT REMOVE!         
        JkWorkersFile /etc/tomcat/jk/workers.properties                   
        Include /var/lib/tomcat/conf/mod_jk.conf                          
        </IfModule>                                                       
                                                                        
   This has been insrted by libapache-java to try to get mod_jk to
   work. unfortunately it doesn't work with Tomcat 4.1, so replace it
   with the following:

        <IfModule mod_jk.c>                                               
        # The following line is for apacheconfig - DO NOT REMOVE!         
        JkWorkersFile /etc/tomcat/jk/workers.properties                   
        JkMount /*.jsp ajp13                                              
        JkMount /Mir ajp13                                                
        JkMount /Mir/* ajp13                                              
        JkMount /servlet ajp13                                            
        jkMount /examples/* ajp13                                                 
        #Include /var/lib/tomcat/conf/mod_jk.conf                         
        </IfModule>                                                       
restart tomcat(as root):
/usr/share/tomcat4/bin/shutdown.sh
/usr/share/tomcat4/bin/startup.sh
restart apache(as root):
apachectl restart

In your browser, check to see if each pogram is working on its own:
http://localhost should give you the debian apache start page
http://localhost:8180 should give you the tomcat start page

now check to see if mod_jk is allowing the two programs to connect:
http://localhost/examples/servlets/index.html should give you the
Tomcat example servlets.  

Once this is working, you should enable the tomcat manager
application:  
cd /usr/share/tomcat4/conf
open tomcat-users.xml in a text editor.  Add a line like this:

<user username="name" password="password" roles="standard,manager,admin"/>

You should now be able to click on the "Manager" link on the Tomcat
home page, log in, and use the Manager functions.  This is extremely
convenient when you're eloading Mir multiple times later on!

(c) install postgres:
apt-get install postgresql postgresql-client postgresql-doc
--> the new postgres package should work fine with Mir.  Make sure you
enable UNICODE, and if asked about JDBC (you shouldn't be) make sure
to enable it as well. if you would like to try a graphical frontend
for the database, find one using

apt-cache show postgresql

fmailiarize yourself with the psql interface, and the function of the
"postgres" user.

(d) install JAI
go to:
http://java.sun.com/products/java-media/jai/downloads/download.html

and download the "CLASSPATH for Linux" version of the JAI package
(1.1.01 works fine, later versions have not been tested by me) to 
/usr/share/tomcat4/common/lib

now:

cd /usr/share/tomcat4/common/lib

gunzip "name_of_file.tar.gz" (don't use the quotes: replace with the
real name of the file you downloaded!)

tar -xvf "name_of_file.tar" 

read the instructions in
/usr/share/tomcat4/common/lib/jai_whatever_version_you_have/INSTALL-jai.txt

Now add the JAI files to your CLASSPATH and LSD_LIBRARY_PATH:  
JAIHOME=$TOMCAT_HOME/common/lib/jai-1_1_1_01/lib; export JAIHOME
CLASSPATH=$JAIHOME/jai_core.jar:$JAIHOME/jai_codec.jar:$JAIHOME/mlibwrapper_jai.jar:$CLASSPATH;
export CLASSPATH
LD_LIBRARY_PATH=.:$JAIHOME:$CLASSPATH; export LD_LIBRARY_PATH

--> make sure to replace "jai-1_1_1_01" in the above with the
version-number of your copy of JAI
--> as above, it's a good idea to add these lines to your .bashrc

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


(1) CONFIGURE MIR!

(a).  get the latest version:

cd to the directory where you would like to install the mir package

cd /absolute/path

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 


(b) customize the config: 

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

now customize config.properties for your needs.  config.properties is
pretty well-documented, but read it carefully.  I had to recompile
several times before I got all the pathnames right.
 

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


(d) Customize the templates
you need to edit the templates before compiling, or not all of your
changes will show up in the produced site.  If this is too
intimidating, don't worry -- you can always recompile!  It only takes
about a minute...

(e) check web.xml!
--> tomcat 4.1 has a different method of composing servlet URL's, so
if you are uasing 4.1, you wil need to make some minor changes to
mir/etc/web.xml

look for sections like this: 
  <servlet-mapping>
        <servlet-name>
            Mir
        </servlet-name>
        <url-pattern>
            /Mir
        </url-pattern>
    </servlet-mapping>

the url-pattern has to change; so replace the above with:
  <servlet-mapping>
        <servlet-name>
            Mir
        </servlet-name>
        <url-pattern>
            /servlet/Mir
        </url-pattern>
    </servlet-mapping>
make sure to do the same for OpenMir and OutputMir.


-------------------------------------------------------------
-------------------------------------------------------------
IMPORTANT!  It is a good idea to skip ahead to (2) and create the
Postgres database at this point.  Then cd back to the mir directory,
and continue.  
-------------------------------------------------------------
-------------------------------------------------------------

(f) compile. Make sure all the environment variables are set as
   indicated in section (0), or build.xml will not run properly:

su
ant

  This should take about a minute.  If you don't get an error, run
   perms.sh:
        sudo perms.sh


Do this as root so the permissions script is able to set
the permissions and owners correctly.
   

(g) Get Tomcat to recognize Mir.
Link in the webapps directory of tomcat to the install directory
(unless you changed the setting in config.properties, 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

dynamically reload Mir: 

http://localhost:8180/manager/stop?path=/Mir
if you're not using the Debian installation, you need to use:
http://localhost:8080/manager/stop?path=/Mir

if you're using Tomcat 3.3, you need to restart Tomcat (consult the
docs for how to do that).  


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

(2) CREATE AND CONLFIGURE THE MIR DATABASE!

Review mir/etc/config.properties.  Look carefully at the entries you
put in the DATABASE SETUP section, especially the Username, Password,
Host, and Name variables.  If you don't know anything about Postgres,
look over the INSTALL.postgresql document, which is very helpful (but
remember, you don't need to install postgresql from scratch
anymore if you're on Debian woody!).  Please do not use the "postgres"
user in config.properties -- this is a serious security risk.  Choose
a username,a password, and a database name, then put those values in
config.properties if you haven't already.  

(a) Create the new database

We create and configure the database as posgresql user "postgres":

   createdb -U postgres --encoding=unicode Mir 
--> here and elsewhere, replace "Mir" with the name you already chose
for your database


(b) 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;
--> again, don't just copy this into the psql command line -- replace
"Mir" and "joshua" with your username and password from config.properties

now exit: 
\q


(c) create base table
cd back to the mir home directory.  now execute the following:

        psql -Upostgres -f dbscripts/create_pg.sql Mir
now quit psql:
        \q
back in the shell, execute the dbscripts:
    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

(d) Grant the required permissions to the new user
First, make your new user into the database administrator for the new
database (instead of postgres):
psql -U postgres Mir
     select * from pg_database;
     select * from pg_user;
you'll see a display like this:
   usename    | usesysid | usecreatedb | usetrace | usesuper | usecatupd |  passwd  | valuntil
--------------+----------+-------------+----------+----------+-----------+----------+----------
 postgres     |        1 | t           | t        | t        | t         | ******** |
 matt         |      100 | t           | f        | t        | t         | ******** |
 mir          |      101 | f           | f        | f        | f         | ******** |

followed by

  datname  | datdba | encoding | datistemplate | datallowconn | datlastsysoid | datvacuumxid | datfrozenxid | datpath
-----------+--------+----------+---------------+--------------+---------------+--------------+--------------+---------

 template1 |      1 |        5 | t             | t            |         16554 |        11258 |   3221236731 |

 template0 |      1 |        5 | t             | f            |         16554 |           49 |           49 |

 Mir       |      1 |        5 | f             | t            |         16554 |        10805 |   3221236278 |
 
note the "usesysid" column for your new user, and the datname for your
new database.  now execute the following line, obviousjly using the
variable you just noted:

update pg_database set datdba=USESYSID_FROM_PG_USER where datname=DATABASENAME

now exit psql: 
\q

save the following lines to a file called set.permissions:

select 'grant all on '||relname||' to Mir;'
from pg_class
where relname not like 'pg%'
order by relname;

-->be sure to replace "Mir" with your username!!!

(e) Apply neccessary changes to config.properties

--> if you folowed the instructions above, you shouldn't have to do
this, but doublecheck!
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.

(f) 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, by inserting these lines:

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

make sure you comment out all other permissions lines in this file!

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.

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

AT THIS POINT YOU SHOULD HAVE A WORKING INSTAATION OF MIR!  CHECK TO
MAKE SURE -- DON'T BOTHER WITH THE REST TILL YOIU'VE MADE MIR WORK ONCE!


Goodies:

(3) Add the dupe prevention trigger to the database:
        cd mir/dbscripts/dupetrigger
        
        There, read INSTALL and follow the instructions.
        

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

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: 2003/01/18 08:44:09 $ - the Mir coders