<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="setup_intro">
  <title>Setting up moregroupware</title>
  
  <para>Setting up moregroupware is described in this and the following
    chapters. Generally you should read this chapter, as it tells you
    about some basic requirements and skills you should have available and
    ready. Then you only need to read one of the following chapters,
    depending on the operating system you want to install moregroupware
    on.
  </para>
  
  <section id="setup_intro_requirements">
    <title>Requirements</title>
    
    <para>To successfully install moregroupware you need at least the
      following software packages on your machine, regardless of the
      operating system in use.
    </para>
    
    <itemizedlist>
      <listitem>
        <para>A webserver (Apache 1.3.x is recommended)</para>
      </listitem>
      <listitem>
        <para>PHP 4.1 or later with XML support</para>
      </listitem>
      <listitem>
        <para>Adatabase server (MySQL 3.23.x or PostgreSQL 7.x)</para>
      </listitem>
      <listitem>
        <para>PHP session auto start must be disabled!</para>
      </listitem>
    </itemizedlist>
    
    <note>
      <para>Using Apache 2.x is NOT recommended at the moment, as it causes
        several problems due to bugs in relation to PHP, at least when run on
        Windows.
      </para>
    </note>
    
    <para>It is necessary to have a . (dot) in your PHP include_path. Look
      at <filename>php.ini</filename> to check this.
    </para>
    
    <para>If want to create GANTT charts in the projects module, you will need
      support for the GD library in your PHP installation. On windows this should
      only be a matter of uncommenting <literal>extension=php_gd.dll</literal>
      in your <filename>php.ini</filename>.
    </para>
    
    <para>You do not need PDF or IMAP support compiled into PHP for the
      current releases, nor do you need XML DOM. We handle those needs
      with PHP-only libraries. It does not harm to have those
      things compiled into PHP, either.
    </para>
    
    <para>We intend to support more databases in the future. Right now
      MySQL works best, and PostgreSQL support is getting better (the core
      modules should work). Other databases will follow later.
    </para>
    
    <para>You should try to run moregroupware with
      <literal>register_globals</literal> disabled, if it doesn't work, it's
      a bug. The same is true for <literal>magic_quotes_gpc</literal> and
      <literal>magic_quotes_runtime</literal>, both should be off. Those are
      not strict requirements, though.
    </para>
    
  </section>
  
  <section id="setup_intro_upgrade">
    <title>Upgrade</title>
    
    <para>When upgrading from one version of moregroupware to the next it
      is recommended that you do so via a clean installation. To upgrade
      otherwise requires an advanced knowledge of SQL and a lot of "hacking"
      to your database.
    </para>
    
    <para>An automatic upgrade function is being worked on, and as soon as
      it is available it will be released, but until then we highly
      recommend you re-install from a clean empty database.
    </para>
    
    <para>If you want to try an upgrade, you should at the upgrade
      instructions in the <link linkend="appendix_upgrade">appendix</link>.
    </para>
    
  </section>
  
  <section id="setup_intro_download">
    <title>Getting more.groupware</title>
    
    <para>Whether you install on Windows, Unix or Mac - you need to get
      the software somehow. This will show you the different ways to
      download more.groupware.
    </para>
    
    <section id="setup_intro_download_releases">
      <title>Downloading more.groupware releases</title>
      
      <para>This is the recommended way of downloading more.groupware for
        most people. You can either go to the
        <ulink url="http://www.moregroupware.org/downloads.php">download
        page at moregroupware.org
      </ulink>
      ,or use the
      <ulink url="http://sourceforge.net/project/showfiles.php?group_id=32034">
      Files section at sourceforge.net.
    </ulink>
  </para>
  
  <para>Either way, there are two flavours available, ZIP archives and
    gzipped TAR archives. You should download the ZIP archive only if you
    want to install on Windows, in all other cases you should go for the
    TAR archive. Note that most Windows software (including WinZip) can
    handle TAR archives just as well. The flavours are identical except
    for the archive format and the format of the line ends inside the
    source files (\n for TAR, \r\n for ZIP).
  </para>
</section>

<section id="setup_intro_download_snaps">
  <title>Downloading more.groupware snapshots</title>
  
  <para>If you want to live on the bleeding edge, using the latest
    code available, but don't want to (or can't) use CVS directly to get
    the sources, download one of the nightly snapshots. They are available
    at the <ulink
    url="http://www.moregroupware.org/snapshots.php">snapshots page at
    moregroupware.org
  </ulink>
  .Be careful though, unless we recommend to
  do this, you are on your own with any problems that might arise from
  using snapshots.
</para>

<note>
  <para>The longer ago the last release took place, the more you
    might want to use a snapshot. But you might want to know what you are
    doing.
  </para>
</note>

<para>Snapshots are only available as gzipped TAR archives. Note that
  most Windows software (including WinZip) can handle TAR archives just
  as well.
</para>
</section>

<section id="setup_intro_download_cvs">
<title>Downloading more.groupware from CVS</title>

<para>Directly downloading more.groupware from the CVS (Concurrent
  Versions System, see <ulink url="http://www.cvshome.org/">www.cvshome.org
</ulink>
)repository
gives you real-time access to the latest and greatest code
available. You should note though, that it might be even buggier than
the snapshots! You still want to do it via CVS? Here we go...
</para>

<para>
<orderedlist>
  <listitem>
    <para>Download WinCVS</para><para>Download WinCVS 1.2 Stable from <ulink url="http://www.wincvs.org/">http://www.wincvs.org/</ulink> and install it.
  </para>
</listitem>
<listitem>
  <para>Configure WinCVS for anonymous checkout and download</para><para>
    <orderedlist>
      <listitem>
        <para>Start WinCvs.</para>
      </listitem>
      <listitem>
        <para>Choose Admin - Preferences.</para>
      </listitem>
      <listitem>
        <para>
          In the field "Enter the CVSROOT" you quote <literal>anonymous@cvs.moregroupware.sourceforge.net:/cvsroot/moregroupware</literal>
        </para>
      </listitem>
      <listitem>
        <para>Set Authentication to "passwd" file on the cvs server. Choose Ok.</para>
      </listitem>
    </orderedlist>
  </para>
</listitem>
<listitem>
  <para>Doing the download</para><para>
    <orderedlist>
      <listitem>
        <para>Select Create - Checkout module</para>
      </listitem>
      <listitem>
        <para>
          Set the module name to <literal>mgw</literal> and select a local folder
          to save the downloaded files
        </para>
      </listitem>
    </orderedlist>
  </para>
</listitem>
<listitem>
  <para>Install more.groupware</para><para>Now follow the appropriate instructions in this manual, according to your used operating system.</para>
</listitem>
</orderedlist>
</para>

</section>

</section>

<section id="setup_intro_preparation">
<title>Preparing the more.groupware setup</title>

<para>After you downloaded more.groupware as per the instructions above, you need to prepare some things on your machine, before you can actually run the setup procedure. Those prepartions naturally differ depending on your operating system. Therefore they are described in seperate chapters following this chapter.</para>

<para><itemizedlist>
<listitem>
<para>
  <link linkend="setup_linux">Installing on Linux</link>
</para>
</listitem>
<listitem>
<para>
  <ulink url="http://www.afp548.com/Articles/Jaguar/moregroupware.html">Installing on MacOS X Server (external site!). This can be seen as an addon to the Linux instructions.
</ulink>

</para>
</listitem>
<listitem>
<para>
<link linkend="setup_windows">Installing on Windows</link>
</para>
</listitem>
</itemizedlist>
</para>

<para>
Read the chapter that fits your choice of operating system. Those chapters contain different flavours of instructions, varying in the amount of detail in which things are described. Pick the one you like best. During those instructions you come to a point telling you to run the setup procedure. This is described in detail in it's own chapter <link linkend="setup_setup">The setup process</link>.
</para>

<important>
<para>
After setup has completed, return to the specific instructions for your operating system to make sure you don't miss any concluding steps. Then read the chapter on <link linkend="setup_security">Securing your more.groupware setup</link>!
</para>
</important>
</section>

<section id="setup_intro_troubleshooting">
<title>Troubleshooting</title>

<para>If you get problems with your more.groupware installation you can visit the
more.groupware support page <ulink url="http://www.moregroupware.org/support.php">http://www.moregroupware.org/support.php
</ulink>
</para>

<para>You can subscribe to one of the mailing lists or browse the
archives, you can visit the more.groupware IRC channel (irc.freenode.net,
#moregroupware) or you can submit bug reports and support requests at
the more.groupware Sourceforge project page <ulink url="https://sourceforge.net/projects/moregroupware/">https://sourceforge.net/projects/moregroupware/
</ulink>
</para>

<para>Remember that more.groupware is a open source project and not a commercial
product! You can not demand a very high service level from the
developers as they are doing all the work in their limited spare
time.
</para>

</section>

<section id="setup_intro_known_bugs">
<title>Known bugs</title>

<section id="setup_intro_known_bugs_webmail2">
<title>Webmail 2</title>

<para>If you try to receive big e-mails with attachements you can get a timeout like:
<programlisting>
Fatal error: Maximum execution time of 60 seconds exceeded in  c:\web\moregroupware\modules\webmail2\inc\class.pop3.inc on line 418
Fatal error: Maximum execution time of 60 seconds exceeded in c:\web\moregroupware\modules\webmail2\inc\pear.php on line 498
</programlisting>
</para>

<para>One dirty way to fix it is to edit
<filename>/modules/webmail2/inc/class.pop3.inc</filename>.
Around line 14 you should find
<programlisting>
var $TIMEOUT    = 60; // Default timeout before giving up on a network operation.
</programlisting>
</para>

<para>If you change from e. g. 60 to 260 you should not so easily get
the timeout.
</para>

<para>if you see memory error messages like:
<programlisting>
Fatal error: Allowed memory size of 8388608 bytes exhauste (tried to allocate 8192 bytes) in ...
</programlisting>
This happens because the webmail2 module downloads email from
the mail server. These email can only be downloaded in one step, that
means the whole email is copied to the memory and then stored on your
harddisk. e.g. an email with the size of 5 MB needs about 10-15 MB in
the memory.
</para>

<para>To fix it you have to increase the memory limit in php.ini:
<programlisting>
memory_limit = 8M ; Maximum amount of memory a script may consume (8MB)
</programlisting>
</para>

<para>Increase this value to '16M' (16 MB) or more (depends on the size
of the emails you get, often there is a limit on the mail server [e.g
10 MB for gmx]).
</para>

<para>If you have problems with sending and/or receiving emails with
large attachments you should try to increase the values for
'post_max_size' and 'upload_max_filesize' in
<filename>php.ini</filename>. Set them to a value high enough,
e.g. '20M'.</para>

</section>

<section id="setup_intro_known_bugs_misc">
<title>General strange behavior of moregroupware</title>

<para>
Check <filename>php.ini</filename> and the parameters below as
mentioned earlier in this guide:
<programlisting>
include_path = "."
register_globals = On
</programlisting>
</para>

<para>Login screen in stead of the data you expected: Internet
Explorer 6 can behave strange together with more.groupware. Some times I have had
good results with erasing temporary files from my computer. After such
a clean up everything often works fine for a while.
</para>

<para>If you get problems with the graphics, login screen in stead of
that you expected etc. a solution can be to change the following line in
<filename>config.inc.php</filename>:
<programlisting>
$appconf["rooturl"] = "http://localhost/moregroupware"; 
</programlisting>
to look like this: 
<programlisting>
$appconf["rooturl"]="http://".$HTTP_SERVER_VARS["HTTP_HOST"]."/moregroupware"; 
</programlisting>
</para>

<para>Wrong URL in config.inc.php: You install moregroupware, log in
and everything is ok. Another person on your network tries to login
and doesn't see the right layout at the login screen (and login
fails).
</para>

<para>Solution: Go to the home directory of mgw, take a look at
<filename>config.inc.php</filename>.  Look for the variables:
<programlisting>
$appconf["rooturl"] = ...
$appconf["rootpath"] = ...
</programlisting>
</para>

<para>
If <literal>$appconf["rooturl"]</literal> is something like
<literal>http://localhost/moregroupware/</literal> or
<literal>http://127.0.0.1/moregroupware/</literal> you have to replace
<literal>localhost</literal> or <literal>127.0.0.1</literal> with your
real IP address that is reachable from other computers in the
net.
</para>

<para>A solution can also be to change from:
<programlisting>
$appconf["rooturl"] = "http://localhost/moregroupware";
</programlisting>
to
<programlisting>
$appconf["rooturl"]="http://".$_SERVER["HTTP_HOST"]."/moregroupware";
</programlisting>
</para>

</section>

</section>

</chapter>
