doc/installation/installation.xml

   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"
   4   [
   5     <!ENTITY MIR_VERSION   "1.1">
   6   ]
   7 >
   8 <book>
   9   <title>Mir CMS 1.1 Installation manual</title>
  10   <bookinfo>
  11     <revhistory>
  12       <revision>
  13         <revnumber>0.0.0</revnumber>
  14
  15         <date>July 2004</date>
  16
  17         <revremark>First steps</revremark>
  18       </revision>
  19       <revision>
  20         <revnumber>0.0.1</revnumber>
  21
  22         <date>October/November 2004</date>
  23
  24         <revremark>First usable version</revremark>
  25       </revision>
  26     </revhistory>
  27
  28     <authorgroup>
  29       <author>
  30         <firstname>Zapata</firstname>
  31         <affiliation>Mir coders</affiliation>
  32       </author>
  33     </authorgroup>
  34   </bookinfo>
  35
  36   <preface>
  37       <abstract>
  38           This document helps system administrators install Mir,
  39           a Java-based Content Management System distributed under
  40           the Gnu Public License.
  41       </abstract>
  42   </preface>
  43
  44   <chapter id="introduction">
  45
  46     <title>Introduction</title>
  47
  48     <section>
  49       <title>Mir</title>
  50
  51       <para>
  52
  53       </para>
  54
  55     </section>
  56
  57     <section>
  58       <title>Version</title>
  59
  60       <para>
  61         This documentation applies to mir version &MIR_VERSION;.
  62       </para>
  63     </section>
  64
  65     <section>
  66       <title>Overview</title>
  67       <para>
  68           In order to make use of Mir, one has to install configure
  69             several required pieces of third party software.
  70
  71       </para>
  72     </section>
  73
  74   </chapter>
  75
  76   <chapter>
  77     <title>Overview</title>
  78
  79     <section>
  80       <title></title>
  81
  82       <para>
  83         <itemizedlist>
  84           <listitem>
  85             Third party software required by mir, such as Postgresql, the Relational
  86             Database Management System Mir requires.
  87           </listitem>
  88           <listitem>
  89             The Mir code itself, normally in the form of a binary
  90             distribution.
  91           </listitem>
  92           <listitem>
  93             Configuration with details like database access parameters.
  94           </listitem>
  95           <listitem>
  96             A custom mir setup, incorporating the look and feel the mir-driven
  97             site should have
  98           </listitem>
  99         </itemizedlist>
 100       </para>
 101
 102     </section>
 103
 104   </chapter>
 105
 106   <chapter>
 107     <title>Installing Mir itself</title>
 108
 109     <section>
 110       <title>Introduction</title>
 111
 112       <para>
 113         <itemizedlist>
 114           <listitem>
 115             Mir versions: x.y.z
 116           </listitem>
 117           <listitem>
 118             Binary distribution, Source distribution,CVS distribution
 119           </listitem>
 120           <listitem>
 121             Mir customization
 122           </listitem>
 123         </itemizedlist>
 124       </para>
 125     </section>
 126
 127     <section>
 128       <title>Obtaining a distribution</title>
 129
 130       <para>
 131       </para>
 132     </section>
 133
 134     <section>
 135       <title>Configuring mir</title>
 136
 137       <para>
 138         <itemizedlist>
 139         </itemizedlist>
 140       </para>
 141
 142     </section>
 143
 144     <section>
 145       <title>Notes for multiple mir installation on a single system</title>
 146
 147       <para>
 148       </para>
 149     </section>
 150
 151     <section>
 152       <title>The most commonly used configuration entries</title>
 153
 154       <para>
 155         <variablelist>
 156           <varlistentry>
 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>
 165
 166             <listitem>
 167               These entries constitute various names and email addresses used in error forms and
 168               within mir's admin interface.
 169             </listitem>
 170           </varlistentry>
 171           <varlistentry>
 172             <term>Mir.DefaultTimezone</term>
 173             <listitem>
 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.
 178
 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>.
 181             </listitem>
 182           </varlistentry>
 183           <varlistentry>
 184             <term>Mir.DefaultDateTimeFormat</term>
 185             <listitem>
 186               The format to use for dates and times in admin, e.g. <literal>yyyy-MM-dd HH:mm</literal>.
 187
 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>
 190             </listitem>
 191           </varlistentry>
 192           <varlistentry>
 193             <term>Mir.Admin.FallbackLanguage</term>
 194             <listitem>
 195             </listitem>
 196           </varlistentry>
 197           <varlistentry>
 198             <term>Mir.Login.DefaultLanguage</term>
 199             <listitem>
 200             </listitem>
 201           </varlistentry>
 202           <varlistentry>
 203             <term>Mir.Login.Languages</term>
 204             <listitem>
 205             </listitem>
 206           </varlistentry>
 207           <varlistentry>
 208             <term>Mir.Admin.ShowLoggedinUsers</term>
 209             <listitem>
 210             </listitem>
 211           </varlistentry>
 212           <varlistentry>
 213             <term>Mir.Localizer.Admin.ListOperationsFlavor</term>
 214             <listitem>
 215             </listitem>
 216           </varlistentry>
 217           <varlistentry>
 218             <term>Mir.Login.Languages</term>
 219             <listitem>
 220             </listitem>
 221           </varlistentry>
 222           <varlistentry>
 223             <term>Mir.Login.Languages</term>
 224             <listitem>
 225             </listitem>
 226           </varlistentry>
 227           <varlistentry>
 228             <term>Mir.Login.Languages</term>
 229             <listitem>
 230             </listitem>
 231           </varlistentry>
 232           <varlistentry>
 233             <term>Mir.Login.Languages</term>
 234             <listitem>
 235             </listitem>
 236           </varlistentry>
 237           <varlistentry>
 238             <term>Mir.Login.Languages</term>
 239             <listitem>
 240             </listitem>
 241           </varlistentry>
 242           <varlistentry>
 243             <term>Mir.Login.Languages</term>
 244             <listitem>
 245             </listitem>
 246           </varlistentry>
 247           <varlistentry>
 248             <term>Mir.Login.Languages</term>
 249             <listitem>
 250             </listitem>
 251           </varlistentry>
 252           <varlistentry>
 253             <term>Mir.Login.Languages</term>
 254             <listitem>
 255             </listitem>
 256           </varlistentry>
 257
 258           <varlistentry>
 259             <term></term>
 260             <listitem>
 261             </listitem>
 262           </varlistentry>
 263         </variablelist>
 264       </para>
 265     </section>
 266   </chapter>
 267
 268   <chapter>
 269     <title>Third party software required by Mir</title>
 270
 271     <section>
 272       <title>A Java Virtual Machine (version 1.3 and up)</title>
 273
 274       <para>
 275         Since Mir is a Java application, a Java virtual machine is
 276         needed to run it.
 277       </para>
 278
 279       <para>
 280         version 1.3+
 281
 282         For linux systems, both IBM and Sun have such a virtual machine
 283         available.
 284       </para>
 285
 286       <para>
 287         JRE versus JDK
 288       </para>
 289
 290       <para>
 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
 293         Foundation</ulink>.
 294
 295         At this moment
 296
 297         Given Mir's commitment to Free Software
 298
 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.
 302
 303         This investigation is ongoing.
 304
 305         Results will be announced on the mir site as well as the mir coders
 306         mailing list.
 307
 308         Until then, one of the aforementioned proprietary virtual machines
 309         is required for Mir.
 310       </para>
 311     </section>
 312
 313     <section>
 314       <title>RDBMS: Postgresql</title>
 315
 316       <para>
 317         The version of Mir described in this document depends on the
 318         Postgresql RDBMS system.
 319
 320         This section will explain the specific side issues applicable
 321         to using it in conjunction with mir.
 322
 323         For general Postgresql information, see <ulink url="http://www.postgresql.org/">The
 324         official Postgresql website</ulink>
 325
 326         Note that databases to be used by mir can be initialized by
 327         a script provided in the mir distribution.
 328       </para>
 329
 330       <section>
 331         <title>Installation</title>
 332
 333         <para>
 334           A normal postgresql installation will suffice for Mir (details can
 335           be found on the postgresql site).
 336
 337           It would be wise however to install support for unicode encoded
 338           databases, since with Mir, these generally work out the best.
 339         </para>
 340       </section>
 341
 342       <section>
 343         <title>Configuration</title>
 344
 345         <para>
 346           <programlisting>
 347             pg_hba.conf
 348           </programlisting>
 349         </para>
 350       </section>
 351
 352       <section>
 353         <title>Maintenance</title>
 354
 355         <para>
 356           The mircoders advise you to make regular backups of your databases,
 357           to prevent accidental loss of data.
 358
 359           Aside from this, there's one important Postgresql-specific maintenance
 360           issue:
 361
 362           <programlisting>
 363             vacuum analyze;
 364           </programlisting>
 365         </para>
 366       </section>
 367
 368       <section>
 369         <title>Practical tips</title>
 370
 371         <para>
 372           A postgresql installation comes with a number of handy tools.
 373
 374           We'll supply you with a brief overview of them.
 375
 376           Further information is available in the man pages of the tools
 377           in question and on the postgresql website.
 378         </para>
 379
 380         <section>
 381           <title><application>psql</application></title>
 382
 383           <para>
 384             <application>psql</application> is postgresql's literal-line
 385             interface to perform queries on databases.
 386           </para>
 387         </section>
 388
 389         <section>
 390           <title><application>pg_dump</application> and <application>pg_restore</application></title>
 391
 392           <para>
 393           </para>
 394         </section>
 395
 396       </section>
 397     </section>
 398
 399     <section>
 400       <title>Java servlet container: Tomcat</title>
 401
 402       <para>
 403         The reccommended Java Servlet Container is Tomcat.
 404
 405         Mir will probably work with Tomcat version 3.3 and up.
 406
 407         For various practical reasons, Tomcat 4 is recommended.
 408
 409         The next version of Mir will most likely require at least Tomcat 4.
 410       </para>
 411
 412       <section>
 413         <title>Installation</title>
 414
 415         <para>
 416           - distributions
 417         </para>
 418       </section>
 419
 420       <section>
 421         <title>Configuration</title>
 422
 423         <para>
 424         </para>
 425
 426         <section>
 427           <title>Pointing tomcat to the mir installation</title>
 428
 429           <para>
 430           </para>
 431         </section>
 432
 433         <section>
 434           <title>Turning off IP logging</title>
 435
 436           <para>
 437
 438           </para>
 439         </section>
 440
 441         <section>
 442           <title>Disabling security</title>
 443
 444           <para>
 445             Future versions of this documentation will contain a
 446             guide to properly configure tomcat's security manager.
 447           </para>
 448         </section>
 449       </section>
 450
 451       <section>
 452         <title>Practical tips</title>
 453
 454         <para>
 455           manager, tomcat restarts, the user running tomcat
 456         </para>
 457
 458       </section>
 459     </section>
 460
 461     <section>
 462       <title>HTTP Server: Apache</title>
 463
 464       <para>
 465         <itemizedlist>
 466           <listitem>enabling SSI</listitem>
 467           <listitem></listitem>
 468         </itemizedlist>
 469       </para>
 470     </section>
 471
 472     <section>
 473       <title>Servlet connector: mod_jk</title>
 474     </section>
 475
 476     <section>
 477       <title>Sun's JAI library</title>
 478
 479       <para>
 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.
 482
 483         As with the virtual machine dependency, the mir coders will also do
 484         its best to move towards a free replacement for JAI.
 485       </para>
 486
 487       <section>
 488         <title>Installation</title>
 489       </section>
 490
 491       <section>
 492         <title>Setting up</title>
 493       </section>
 494     </section>
 495   </chapter>
 496
 497
 498   <chapter>
 499     <title>Setting up Mir on Debian</title>
 500
 501     <section>
 502       <title>Introduction</title>
 503
 504       <para>
 505         For users of the Debian GNU/Linux distribution, this chapter offers
 506         easy steps to install mir.
 507       </para>
 508
 509       <para>
 510          Most of the third part software needed to run Mir, is available as
 511          packages in debian distributions from woody on.
 512
 513          This chapter assumes the distribution, though most should be applicable
 514          to newer distributions as well.
 515       </para>
 516     </section>
 517     <section>
 518       <title>Postgresql</title>
 519
 520       <para>
 521          <application>Postgresql</application> is available in debian under the
 522          package postgresql.
 523
 524          <informalexample>
 525            <programlisting><literal>apt-get install postgresql</literal></programlisting>
 526          </informalexample>
 527       </para>
 528
 529       <para>
 530         By default, postgresql in Debian is configured to use
 531         <quote>ident</quote> authentication and <quote>sameuser</quote>
 532         authorization for local users.
 533
 534         This means a local user can connect as the postgresql user with the
 535         same name.
 536
 537         For Mir, it's required to have <quote>password</quote> authentication.
 538
 539         Therefore, in <filename>/etc/postgresql/pg_hba.conf</filename> a
 540         change needs to be made:
 541
 542         The line containing the localhost configuration should be changed to look
 543         like:
 544           <programlisting>
 545 host         all         127.0.0.1     255.0.0.0           password
 546           </programlisting>
 547
 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.
 550
 551       </para>
 552       <para>
 553         For convenience reasons, it's also recommended to use password
 554         authentication for the local domain.
 555
 556         For this, first a proper password needs to be selected for the postgres
 557
 558         super user:
 559            <informalexample>
 560              <programlisting><literal>su postgres</literal>
 561 <literal>psql template1</literal>
 562 # alter user postgres with password 'xxxxxxx';
 563 /q</programlisting>
 564            </informalexample>
 565
 566         Then, the line with local authentication in
 567         <filename>/etc/postgresql/pg_hba.conf</filename> should be
 568         altered:
 569           <programlisting>
 570 local        all                                           password
 571           </programlisting>
 572       </para>
 573       <para>
 574
 575       </para>
 576     </section>
 577     <section>
 578       <title>Tomcat</title>
 579         <para>
 580            <application>Tomcat 4</application> can be found in Debian-package tomcat4.
 581            <informalexample>
 582              <programlisting><literal>apt-get install tomcat4</literal></programlisting>
 583            </informalexample>
 584         </para>
 585         <para>
 586            The security manager needs to be disabled by editing
 587             <filename>/etc/default/tomcat4</filename>
 588              and setting the option <option>TOMCAT4_SECURITY</option>
 589              to <literal>"no"</literal>
 590            <informalexample>
 591              <programlisting><option>TOMCAT4_SECURITY</option> = <literal>"no"</literal></programlisting>
 592            </informalexample>
 593         </para>
 594         <para>
 595            It is reccommended to disable ip logging.
 596
 597            This can be done by editing
 598             <filename>/usr/share/tomcat4/conf/server.xml</filename>
 599              and deleting or commenting out the <quote>acces log valve</quote>:
 600            <informalexample>
 601              <programlisting>
 602 &lt;!--
 603 &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
 604  directory="logs"  prefix="localhost_access_log." suffix=".txt"
 605  pattern="common" /&gt;
 606
 607   --&gt;
 608               </programlisting>
 609            </informalexample>
 610         </para>
 611     </section>
 612   </chapter>
 613 </book>
 614
 615
 616
 617
 618
 619