egroupware/doc/HOWTO.sgml

<!doctype linuxdoc system>

<!-- LinuxDoc file was created by hand by <Dan Kuykendall> 7 July 2000 -->
<article>
<title>
  phpGroupWare HOWTO
</title>
<author>
  Joseph Engo &lt;jengo@phpgroupware.org&gt;,
  Dan Kuykendall &lt;dan@kuykendall.org&gt;
</author>
<date>
  v1.0, 7 July 2000
</date>
<abstract>
  This document explains how to install and configure phpGroupWare.
</abstract>

<toc>
<sect>Introduction
<p>
  phpGroupWare is a web based groupware application that includes integrated features such as 
  email, calendar, todo list, address book, file manager, headline news, and a trouble ticket system.
  <p>It should run on all systems where PHP is avalible and currently supports MySQL and PostgreSQL.
</p>
<sect1>What is phpGroupWare and why should I use it?
<p>
  phpGroupWare is:<p>
  phpGroupWare is a web based groupware application that includes integrated features such as 
  email, calendar, todo list, address book, file manager, headline news, and a trouble ticket system.<P>

  You should use it if:<p>
  You would like a powerful groupware system that can be access from anywhere on the Internet. 
  For companies with a distributed user base, it's an ideal solution. Oh, and did I mention that its FREE?
</p>
<sect>Installation
<sect1>Requirements
<p>
  You will need PHP compiled and installed on your system.  You will also need MySQL or PostgreSQL setup. 
  If you are planning on using the email system, you will need to have an IMAP server installed and IMAP support compiled into PHP.
  You can have it installed as an Apache module or command line version, the Apache module is prefered.
  We will assume that you are running on a Linux or other Unix system for these steps. 
  Windows is supported, but there is no documentation for it currently.
</p>
<sect1>Tested Systems
<p>
  On Linux 2.2.x
  <itemize>
    <item>PHP 3.0.15+ / PHP 4.0.x
    <item>Apache 1.3.x
    <item>MySQL 3.22.25 or PostgreSQL 7.0.x
    <item>Courier-IMAP 0.33+
  </itemize>

  We have reports of it working on Windows NT, but no details at this time.
</p>
<sect1>Tested Systems
<p>
  After you have met the system requirements, unpack the tarball in the html 
  directory of your webserver. (eg, /home/httpd/html)
  <p>
  The first step is to setup the database and create the tables needed.  In the 
  doc directory there is a file called create_tables.(name of your database)
</p>
<sect2>Installation with MySQL
<p>
  We will assume that you are using the database named phpgroupware.<p>
  <tt>$ mysql phpgroupware -u username -p < create_tables.mysql</tt>
</p>
<sect2>Installation with PostgreSQL
<p>
  We will assume that you are using the database named phpgroupware.<p>
  <tt>$ psql -d phpgroupware -U username < create_tables.pgsql</tt>
</p>
<sect1>Configure phpGroupWare
<p>
  Change to the inc directory. <newline>
  Edit the file called config.inc.php to point to the location of your include files.
<tscreen>
  Some people might prefer to install their include files in a directory which is not world viewable.  
  For this, you will need to move everything except config.inc.php into another directory 
  and point config.inc.php to that directory.  For most installations, the current location 
  of these file should be fine.
</tscreen>
  Edit globalconfig.inc.php to reflect your system settings.  You can choose which programs 
  you would like to have available to your system.<newline>
  For example, if you do not have access to a IMAP server, you can change 
  <tt>$installed["email"] = "Y"; </tt> to <tt>$installed["email"] = "N";</tt><newline>
  This would make this program unavaiable to all users regardless of their permissions.
<p>
  If you are using the email system you will need to create a temporary directory 
  where file uploads will be stored.  For security reasons, you should <tt>chown
  nobody.nobody</tt> and <tt>chmod 700</tt> to that directory.  Depending on your system configuration.  
  Default installs of Apache normally run as the user nobody.  You may need your system 
  administrator to do this for you if you do not have root access.
<p>
  If you do not have access to root, create this file and run it.
<verb>
  <?php 
    if (mkdir("/path/to/temp/directory",0700)) { 
      echo "Directory created successfully"; 
    } else { 
      echo "Error creating directory"; 
    }
</verb>
  If you have access to cron, you may want to setup the files in the cron 
  directory.
<p>
  stalesessions.pl - There are 2 reasons for this file. 
<itemize>
  <item>Users always forget to logout. This way the session doesn't sit around forever, creating a possible security risk. 
  <item>The email system requires plain text passwords which are stored in the sessions table.
</itemize>

  This file is not required, you can simply uncomment the lines indicated in session.class in update_dla(). 
  This will require an extra query during every transaction which could cause performance 
  problems.  Also, if there are no logins in a few days, they will sit around and 
  wait for someone to login before they are deleted.  If you go this route, you 
  will need to edit the number of seconds until they are deleted.  It defaults to 2 hours 
  (7200 secs).  If you choose to use the cron program, simply edit the settings 
  for your database and uncomment the line for your database type.
<p>
  stale_uploads.pl - This will delete file attachments for messages that where not 
  completed.  If a users browser crashes, internet connection dies, etc, their
  files will sit there forever unless deleted.  You could add a few lines to 
  logout.php that will look in the temp directory for any stale uploads and delete 
  them.  But, once again, it becomes a performance issue.
<p>
  If your config is setup properly you can now login.  Point your browser to the 
  installed location and login with the username <tt>demo</tt> and the password is <tt>1234</tt><newline>
  At this point it would be a good idea to create a new user and delete the old 
  one.
</p>
<sect>About this document
<sect1>New versions 
<p>
  The newest version of this document can be found on our website <url url="http://www.phpgroupware.org"> as SGML source, HTML, or TEXT.
</p>
<sect1>Comments 
<p>
  Comments on this HOWTO should be directed to the phpGroupWare developers mailing list 
  <url url="mailto:phpgroupware-developers@lists.sourceforge.net" name="phpgroupware-developers@lists.sourceforge.net">.<P>
  To subscribe, go to <url url="http://sourceforge.net/mail/?group_id=7305"
name="http://sourceforge.net/mail/?group_id=7305">
</p>
<sect1>History 
<p>
  This document was started by Joseph Engo and reworked by Dan Kuykendall.
</p>
<sect1>Version History 
<p>
  Old Version
</p>
<p>
<itemize>
  <item>Created by Jengo, wasn't in SGML HOWTO format.
</itemize>
<p>
  v1.0 (July 6, 2000)
</p>
<p>
<itemize>
  <item>Built proper SGML version.
  <item>Included the FAQ.
  <item>Other minor additions.
</itemize>
</p>
<sect1>Copyrights and Trademarks 
<p>
  Copyright (c)  Dan Kuykendall.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation
</p>
<p>
  A copy of the license is available at
  <url url="http://www.gnu.org/copyleft/fdl.txt" name="GNU Free Documentation License">.
</p>
<sect1>Acknowledgements and Thanks 
<p>
  Thanks to Joesph Engo for starting phpGroupWare (at the time called webdistro) and the core of this HOWTO. 
  Thanks to all the developers and users who contribute to making phpGroupWare such a success.
</p>
</article>