1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
5 <!ENTITY MIR_VERSION "1.1">
9 <title>Mir CMS 1.1 Installation manual</title>
13 <revnumber>0.0.0</revnumber>
15 <date>July 2004</date>
17 <revremark>First steps</revremark>
20 <revnumber>0.0.1</revnumber>
22 <date>October/November 2004</date>
24 <revremark>First usable version</revremark>
30 <firstname>Zapata</firstname>
31 <affiliation>Mir coders</affiliation>
38 This document helps system administrators install Mir,
39 a Java-based Content Management System distributed under
40 the Gnu Public License.
44 <chapter id="introduction">
46 <title>Introduction</title>
58 <title>Version</title>
61 This documentation applies to mir version &MIR_VERSION;.
66 <title>Overview</title>
68 In order to make use of Mir, one has to install configure
69 several required pieces of third party software.
77 <title>Overview</title>
85 Third party software required by mir, such as Postgresql, the Relational
86 Database Management System Mir requires.
89 The Mir code itself, normally in the form of a binary
93 Configuration with details like database access parameters.
96 A custom mir setup, incorporating the look and feel the mir-driven
107 <title>Installing Mir itself</title>
110 <title>Introduction</title>
118 Binary distribution, Source distribution,CVS distribution
128 <title>Obtaining a distribution</title>
135 <title>Configuring mir</title>
145 <title>Notes for multiple mir installation on a single system</title>
152 <title>The most commonly used configuration entries</title>
157 <term><literal>Mir.Name</literal></term>
158 <term><literal>Mir.Shortname</literal></term>
159 <term><literal>Mir.Contact-email.address</literal></term>
160 <term><literal>Mir.Contact-email.name</literal></term>
161 <term><literal>Mir.Tech-email.address</literal></term>
162 <term><literal>Mir.Tech-email.name</literal></term>
163 <term><literal>Mir.Public-email.address</literal></term>
164 <term><literal>Mir.Public-email.name</literal></term>
167 These entries constitute various names and email addresses used in error forms and
168 within mir's admin interface.
172 <term>Mir.DefaultTimezone</term>
174 The default timezone to be used for showing dates and times.
175 Values like <literal>Europe/Amsterdam</literal> are highly
176 reccommended, since these take daylight savings time into
177 account where applicable.
179 For a full list of possible values, see:
180 <ulink url="http://www.fnal.gov/docs/products/crl/misc/Time_Zone_Listing.txt">here</ulink>.
184 <term>Mir.DefaultDateTimeFormat</term>
186 The format to use for dates and times in admin, e.g. <literal>yyyy-MM-dd HH:mm</literal>.
188 For the allowed codes and their meanings, see
189 <ulink url="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">here</ulink>
193 <term>Mir.Admin.FallbackLanguage</term>
198 <term>Mir.Login.DefaultLanguage</term>
203 <term>Mir.Login.Languages</term>
208 <term>Mir.Admin.ShowLoggedinUsers</term>
213 <term>Mir.Localizer.Admin.ListOperationsFlavor</term>
218 <term>Mir.Login.Languages</term>
223 <term>Mir.Login.Languages</term>
228 <term>Mir.Login.Languages</term>
233 <term>Mir.Login.Languages</term>
238 <term>Mir.Login.Languages</term>
243 <term>Mir.Login.Languages</term>
248 <term>Mir.Login.Languages</term>
253 <term>Mir.Login.Languages</term>
269 <title>Third party software required by Mir</title>
272 <title>A Java Virtual Machine (version 1.3 and up)</title>
275 Since Mir is a Java application, a Java virtual machine is
282 For linux systems, both IBM and Sun have such a virtual machine
291 Neither the IBM nor the SUN Virtual Machine constitute free
292 software as definied by the <ulink url="http://www.fsf.org">Free Software
297 Given Mir's commitment to Free Software
299 Alternatives to propietary JVMs are actively sought by the mir coders,
300 especially regarding gnu's gjc and classpath projects and the
301 sable virtual machine.
303 This investigation is ongoing.
305 Results will be announced on the mir site as well as the mir coders
308 Until then, one of the aforementioned proprietary virtual machines
314 <title>RDBMS: Postgresql</title>
317 The version of Mir described in this document depends on the
318 Postgresql RDBMS system.
320 This section will explain the specific side issues applicable
321 to using it in conjunction with mir.
323 For general Postgresql information, see <ulink url="http://www.postgresql.org/">The
324 official Postgresql website</ulink>
326 Note that databases to be used by mir can be initialized by
327 a script provided in the mir distribution.
331 <title>Installation</title>
334 A normal postgresql installation will suffice for Mir (details can
335 be found on the postgresql site).
337 It would be wise however to install support for unicode encoded
338 databases, since with Mir, these generally work out the best.
343 <title>Configuration</title>
353 <title>Maintenance</title>
356 The mircoders advise you to make regular backups of your databases,
357 to prevent accidental loss of data.
359 Aside from this, there's one important Postgresql-specific maintenance
369 <title>Practical tips</title>
372 A postgresql installation comes with a number of handy tools.
374 We'll supply you with a brief overview of them.
376 Further information is available in the man pages of the tools
377 in question and on the postgresql website.
381 <title><application>psql</application></title>
384 <application>psql</application> is postgresql's literal-line
385 interface to perform queries on databases.
390 <title><application>pg_dump</application> and <application>pg_restore</application></title>
400 <title>Java servlet container: Tomcat</title>
403 The reccommended Java Servlet Container is Tomcat.
405 Mir will probably work with Tomcat version 3.3 and up.
407 For various practical reasons, Tomcat 4 is recommended.
409 The next version of Mir will most likely require at least Tomcat 4.
413 <title>Installation</title>
421 <title>Configuration</title>
427 <title>Pointing tomcat to the mir installation</title>
434 <title>Turning off IP logging</title>
442 <title>Disabling security</title>
445 Future versions of this documentation will contain a
446 guide to properly configure tomcat's security manager.
452 <title>Practical tips</title>
455 manager, tomcat restarts, the user running tomcat
462 <title>HTTP Server: Apache</title>
466 <listitem>enabling SSI</listitem>
467 <listitem></listitem>
473 <title>Servlet connector: mod_jk</title>
477 <title>Sun's JAI library</title>
480 In addition to a virtual machine, Mir depends at this time on another
481 piece of non-free software, namely the JAI image library from Sun.
483 As with the virtual machine dependency, the mir coders will also do
484 its best to move towards a free replacement for JAI.
488 <title>Installation</title>
492 <title>Setting up</title>
499 <title>Setting up Mir on Debian</title>
502 <title>Introduction</title>
505 For users of the Debian GNU/Linux distribution, this chapter offers
506 easy steps to install mir.
510 Most of the third part software needed to run Mir, is available as
511 packages in debian distributions from woody on.
513 This chapter assumes the distribution, though most should be applicable
514 to newer distributions as well.
518 <title>Postgresql</title>
521 <application>Postgresql</application> is available in debian under the
525 <programlisting><literal>apt-get install postgresql</literal></programlisting>
530 By default, postgresql in Debian is configured to use
531 <quote>ident</quote> authentication and <quote>sameuser</quote>
532 authorization for local users.
534 This means a local user can connect as the postgresql user with the
537 For Mir, it's required to have <quote>password</quote> authentication.
539 Therefore, in <filename>/etc/postgresql/pg_hba.conf</filename> a
540 change needs to be made:
542 The line containing the localhost configuration should be changed to look
545 host all 127.0.0.1 255.0.0.0 password
548 This means that any user from localhost can connect as any postgresql
549 user, as long as she can authenticate herself with the password.
553 For convenience reasons, it's also recommended to use password
554 authentication for the local domain.
556 For this, first a proper password needs to be selected for the postgres
558 super user. As root, do:
560 <programlisting><literal>su postgres</literal>
561 <literal>psql template1</literal>
562 # alter user postgres with password 'xxxxxxx';
566 Then, the line with local authentication in
567 <filename>/etc/postgresql/pg_hba.conf</filename> should be
574 Don't forget to restart the database so that these changes will be taken
575 into acount (/etc/init.d/postgresql restart).
579 <title>Tomcat</title>
581 <application>Tomcat 4</application> can be found in Debian-package tomcat4.
583 <programlisting><literal>apt-get install tomcat4</literal></programlisting>
587 The security manager needs to be disabled by editing
588 <filename>/etc/default/tomcat4</filename>
589 and setting the option <option>TOMCAT4_SECURITY</option>
590 to <literal>"no"</literal>
592 <programlisting><option>TOMCAT4_SECURITY</option> = <literal>"no"</literal></programlisting>
596 It is reccommended to disable ip logging.
598 This can be done by editing
599 <filename>/usr/share/tomcat4/conf/server.xml</filename>
600 and deleting or commenting out the <quote>acces log valve</quote>:
604 <Valve className="org.apache.catalina.valves.AccessLogValve"
605 directory="logs" prefix="localhost_access_log." suffix=".txt"
606 pattern="common" />