2000-08-18 05:24:22 +02:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
|
|
<HTML>
|
|
|
|
|
<HEAD>
|
|
|
|
|
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
|
|
|
|
|
<TITLE> phpGroupWare HOWTO</TITLE>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</HEAD>
|
|
|
|
|
<BODY>
|
|
|
|
|
<H1> phpGroupWare HOWTO</H1>
|
|
|
|
|
|
|
|
|
|
<H2>Joseph Engo <jengo@phpgroupware.org>,
|
2000-09-28 17:08:47 +02:00
|
|
|
Dan Kuykendall <dan@kuykendall.org></H2> v1.1, 28 September 2000
|
2000-08-18 05:24:22 +02:00
|
|
|
<P><HR>
|
|
|
|
|
<EM> This document explains how to install and configure phpGroupWare.</EM>
|
|
|
|
|
<HR>
|
|
|
|
|
<H2><A NAME="s1">1. Introduction</A></H2>
|
|
|
|
|
|
|
|
|
|
<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.
|
2000-09-27 17:10:44 +02:00
|
|
|
<P>It should run on all systems where PHP is available and currently supports MySQL and PostgreSQL.
|
2000-08-18 05:24:22 +02:00
|
|
|
<H2>1.1 What is phpGroupWare and why should I use it?</H2>
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
<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?
|
|
|
|
|
<H2><A NAME="s2">2. Installation</A></H2>
|
|
|
|
|
|
|
|
|
|
<H2>2.1 Requirements</H2>
|
|
|
|
|
|
|
|
|
|
<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.
|
2000-09-27 17:10:44 +02:00
|
|
|
You can have it installed as an Apache module or command line version, the Apache module is preferred.
|
2000-08-18 05:24:22 +02:00
|
|
|
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.
|
|
|
|
|
<H2>2.2 Tested Systems</H2>
|
|
|
|
|
|
|
|
|
|
<P>On Linux 2.2.x
|
|
|
|
|
<UL>
|
|
|
|
|
<LI>PHP 3.0.15+ / PHP 4.0.x</LI>
|
|
|
|
|
<LI>Apache 1.3.x</LI>
|
|
|
|
|
<LI>MySQL 3.22.25 or PostgreSQL 7.0.x</LI>
|
2000-09-27 23:18:02 +02:00
|
|
|
<LI>Courier-IMAP 0.33+ and/or qmail 1.03 for POP3 access</LI>
|
2000-08-18 05:24:22 +02:00
|
|
|
</UL>
|
2000-10-11 07:47:29 +02:00
|
|
|
<P>We have reports of phpGroupWare working on Windows NT and OS/2, and using Oracle as the database.
|
2000-09-27 23:18:02 +02:00
|
|
|
<H2>2.3 Obtaining phpGroupWare</H2>
|
|
|
|
|
|
|
|
|
|
<P>While we are still in the Beta phase of phpGroupWare, you may
|
|
|
|
|
want to track the CVS copy as closely as possible. The released
|
|
|
|
|
versions are more stable, but often contain bugs that have been fixed
|
|
|
|
|
in the CVS version.
|
|
|
|
|
<H3>Released Versions</H3>
|
|
|
|
|
|
|
|
|
|
<P>The downloads section on the
|
|
|
|
|
<A HREF="http://www.phpgroupware.org/">http://www.phpgroupware.org/</A> site
|
|
|
|
|
contains links to the most recent releases, and several mirror sites
|
|
|
|
|
for the releases.
|
|
|
|
|
<H3>Developer's version from CVS</H3>
|
|
|
|
|
|
|
|
|
|
<P>If you have never used CVS, you may want to read through the doucmentation
|
|
|
|
|
found at
|
|
|
|
|
<A HREF="http://www.cvshome.org/">http://www.cvshome.org/</A>.
|
|
|
|
|
The CVS pages for the core and apps projects can be found at
|
|
|
|
|
<A HREF="http://sourceforge.net/cvs/?group_id=7305">phpGroupWare Core CVS</A>, and
|
|
|
|
|
<A HREF="http://sourceforge.net/cvs/?group_id=9787">phpGroupWare Apps CVS</A>.
|
|
|
|
|
Follow the directions for <B>Anonymous CVS access</B> and you should
|
|
|
|
|
have the most recent development copy of phpGroupWare in no time.
|
|
|
|
|
<H2>2.4 Installing on Tested Systems</H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<P>After you have met the system requirements, unpack the tarball in the html
|
|
|
|
|
directory of your webserver. (eg, /home/httpd/html)
|
2000-10-11 07:47:29 +02:00
|
|
|
<H2>2.5 Create a database and user for phpGroupWare</H2>
|
|
|
|
|
|
|
|
|
|
<P>You must create a database for phpGroupWare to use,
|
|
|
|
|
and we strongly recommend adding a user that only
|
|
|
|
|
has permission to this new database for phpGroupWare's
|
|
|
|
|
exclusive use (for security).
|
|
|
|
|
<P>Note the host the database engine is on, user, password and database name, you will need them soon.
|
|
|
|
|
<H2>2.6 Configure phpGroupWare</H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
2000-09-27 17:10:44 +02:00
|
|
|
<P>Copy the <CODE>header.inc.php.sample</CODE> file to
|
|
|
|
|
<CODE>header.inc.php</CODE> and edit the file, following the
|
|
|
|
|
directions in the comments.
|
2000-09-28 17:08:47 +02:00
|
|
|
<P>Then point your browser to phpgroupware/setup/ which will
|
|
|
|
|
create (or upgrade) the database tables.
|
|
|
|
|
You wil be asked to login, using the password set in
|
|
|
|
|
<CODE>header.inc.php</CODE>. Setup will attempt to determine what version
|
|
|
|
|
of the phpGroupWare database you have installed, and upgrade to the most recent
|
|
|
|
|
version.
|
|
|
|
|
<P><B>NOTE:</B>The developers are concentrating on getting the beta
|
|
|
|
|
working, and have not spent a great deal of time building upgrade scripts from the
|
|
|
|
|
alpha versions of phpGroupWare. You are advised to backup your existing alpha
|
|
|
|
|
database before running the setup script to avoid problems!
|
|
|
|
|
<P>If you get no error messages, continue on to phpgroupware/setup/config.php
|
|
|
|
|
to configure phpGroupWare to your system.
|
2000-08-18 05:24:22 +02:00
|
|
|
<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 <CODE>chown
|
|
|
|
|
nobody.nobody</CODE> and <CODE>chmod 700</CODE> 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.
|
|
|
|
|
<PRE>
|
|
|
|
|
<?php
|
|
|
|
|
if (mkdir("/path/to/temp/directory",0700)) {
|
|
|
|
|
echo "Directory created successfully";
|
|
|
|
|
} else {
|
|
|
|
|
echo "Error creating directory";
|
|
|
|
|
}
|
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
<UL>
|
|
|
|
|
<LI>Users always forget to logout. This way the session doesn't sit around forever, creating a possible security risk. </LI>
|
|
|
|
|
<LI>The email system requires plain text passwords which are stored in the sessions table.</LI>
|
|
|
|
|
</UL>
|
2000-09-07 23:10:17 +02:00
|
|
|
<P>This file is not required, you can simply disable cron_apps in the admin -> applications section
|
2000-09-27 17:10:44 +02:00
|
|
|
to clean out the sessions table during login and logout.
|
2000-08-18 05:24:22 +02:00
|
|
|
<P>stale_uploads.pl - This will delete file attachments for messages that where not
|
2000-09-27 17:10:44 +02:00
|
|
|
completed. If a users browser crashes, Internet connection dies, etc, their
|
2000-08-18 05:24:22 +02:00
|
|
|
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.
|
2000-09-27 17:10:44 +02:00
|
|
|
<H2><A NAME="s3">3. Testing the install</A></H2>
|
|
|
|
|
|
2000-08-18 05:24:22 +02:00
|
|
|
<P>If your config is setup properly you can now login. Point your browser to the
|
|
|
|
|
installed location and login with the username <CODE>demo</CODE> and the password is <CODE>1234</CODE><BR>
|
2000-09-27 17:10:44 +02:00
|
|
|
At this point it would be a good idea to create a new user with administrative privileges and
|
|
|
|
|
delete the old one.
|
|
|
|
|
<H2><A NAME="s4">4. Installing additional applications</A></H2>
|
|
|
|
|
|
|
|
|
|
<P>Once you have the core phpGroupWare install up and running,
|
|
|
|
|
you may want to download and install additional applications.
|
|
|
|
|
<P>You should consult any <CODE>README</CODE> or <CODE>INSTALL</CODE>
|
|
|
|
|
files that come with the new application first, as most require you
|
|
|
|
|
to create additional tables in the database, and add additional
|
|
|
|
|
translation data to the lang table (typically a file called <CODE>lang.sql</CODE>)
|
|
|
|
|
<P>You install the new application within the phpGroupWare install tree by
|
2000-10-11 07:47:29 +02:00
|
|
|
placing the application directory under the root phpGroupWare directory,
|
2000-09-27 17:10:44 +02:00
|
|
|
and enabling the application through the Administration page.
|
|
|
|
|
<P>For example, this is the process to install the
|
|
|
|
|
Headlines application (see
|
|
|
|
|
<A HREF="http://sourceforge.net/phpgwapps/">http://sourceforge.net/phpgwapps/</A> for
|
|
|
|
|
more on this and other applications).
|
|
|
|
|
<UL>
|
|
|
|
|
<LI>Download the .tar.gz file for the application, or check out the source
|
|
|
|
|
with cvs with
|
|
|
|
|
<PRE>
|
|
|
|
|
export CVSROOT=':pserver:anonymous@cvs.phpgroupware.sourceforge.net:/cvsroot/phpgwapps'
|
|
|
|
|
cvs login (just hit enter if prompted for a password)
|
|
|
|
|
cvs co headlines
|
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
</LI>
|
|
|
|
|
<LI>Move the <CODE>headlines</CODE> directory into your phpGroupWare
|
|
|
|
|
install directory.
|
|
|
|
|
</LI>
|
|
|
|
|
<LI>Log into phpGroupWare as an administrative user, and go to the Administration page.
|
|
|
|
|
</LI>
|
|
|
|
|
<LI>In the first section, choose the <CODE>Applications</CODE> link
|
|
|
|
|
</LI>
|
|
|
|
|
<LI>Click on add, and fill in the form.
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><B>Application name</B><DD><P>should be identical to the name
|
|
|
|
|
of the directory you moved into the phpGroupWare install, in this case use <CODE>headlines</CODE>
|
|
|
|
|
<DT><B>Application Title</B><DD><P>this is shown in the navigation bar and other places to refer to the
|
|
|
|
|
new application. Enter <CODE>Headlines</CODE> for this example.
|
|
|
|
|
<DT><B>Enabled</B><DD><P>This can be used to disable an application for all users temporially. You
|
|
|
|
|
should normal check the box to enable the application.
|
|
|
|
|
</DL>
|
|
|
|
|
</LI>
|
|
|
|
|
<LI>Back in the Administration page, you need to enable the application for specific users
|
|
|
|
|
or user groups by editing them, and checking the new <CODE>Headlines</CODE> box that appears
|
|
|
|
|
in the middle of the account editing page.</LI>
|
|
|
|
|
<LI>Once you have added the Headlines app to your account, you should see a Headlines
|
|
|
|
|
entry in the Administration and Preferences pages, and there should be an icon for
|
|
|
|
|
the Headlines application in the navigation bar.</LI>
|
|
|
|
|
<LI>Once you enable a few of the Headlines sites through the Administration page link, you
|
|
|
|
|
should see headlines grabbed from the sites you selected when you click on the Headlines
|
|
|
|
|
icon in the navigation bar.</LI>
|
|
|
|
|
</UL>
|
|
|
|
|
<H2><A NAME="s5">5. Trouble-shooting</A></H2>
|
|
|
|
|
|
|
|
|
|
<P><B>WARNING!</B> phpGroupWare is still Beta software, expect some bugs
|
|
|
|
|
along the way. If you run into a problem not discussed here, contact us
|
|
|
|
|
through one of the methods listed on the website.
|
|
|
|
|
<P>The phpGroupWare developers can often be seen hanging out in #phpGroupWare
|
|
|
|
|
on irc.openprojects.net if you require real-time help.
|
|
|
|
|
<P>Also check the FAQ in this directory for additional common questions,
|
|
|
|
|
it is available as FAQ.sgml, FAQ.txt and FAQ.html
|
|
|
|
|
<P>
|
|
|
|
|
<H2>5.1 I get "Unable to open mailbox" when using the email application</H2>
|
|
|
|
|
|
|
|
|
|
<P>At the time of this writing (2000-09-27) you must use the same
|
|
|
|
|
username and password in phpGroupWare that you use to log into
|
|
|
|
|
your mail server. If you change your password and it still isn't working,
|
|
|
|
|
try logging out of phpGroupWare (the rightmost icon in the navigation bar)
|
|
|
|
|
and then log back in.
|
|
|
|
|
<P>An preference page to edit the email settings is being developed, and should
|
|
|
|
|
appear shortly after the first beta release.
|
|
|
|
|
<H2>5.2 It seems to hang when I try to read my mail</H2>
|
|
|
|
|
|
|
|
|
|
<P>This is often a problem if you are using POP3 instead of IMAP, and you have
|
|
|
|
|
more than a few hundred messages in your mailbox.
|
|
|
|
|
<P>By default, php is set up to time-out a request that takes over 30 seconds
|
|
|
|
|
to complete. phpGroupWare must do a lot of work the first time your POP3 mailbox
|
|
|
|
|
is opened, and every time you get new mail, which may take more than the 30
|
|
|
|
|
second timeout.
|
|
|
|
|
<P>You can either clean up your mailbox with another mail program, or
|
|
|
|
|
add the line
|
|
|
|
|
<HR>
|
|
|
|
|
<PRE>
|
|
|
|
|
set_time_limit(0);
|
|
|
|
|
</PRE>
|
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
|
|
to the top of the inc/phpgwapi/phpgw_msg_pop3.inc.php file, just before
|
|
|
|
|
the line
|
|
|
|
|
<PRE>
|
|
|
|
|
class msg extends msg_common
|
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>If you choose to edit the file, be patient when loading a large POP3
|
|
|
|
|
mailbox - the author tested against a mailbox with 2500 messages in it,
|
|
|
|
|
but it took 15 minutes to load the page. We highly suggest you use IMAP
|
|
|
|
|
if you expect to have more than a few hundred messages in your mailbox.
|
|
|
|
|
<H2>5.3 When I log in I see the directory listing instead of a web page</H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
2000-09-27 17:10:44 +02:00
|
|
|
<P>If you are using Apache, this often means you need to add
|
|
|
|
|
<CODE>.php</CODE> to the <CODE>DirectoryIndex</CODE> line in your httpd.conf file.
|
|
|
|
|
<P>For example:
|
|
|
|
|
<HR>
|
|
|
|
|
<PRE>
|
|
|
|
|
DirectoryIndex index.php index.php3 index.html index.htm index.cgi
|
|
|
|
|
</PRE>
|
|
|
|
|
<HR>
|
|
|
|
|
<H2>5.4 I get garbage that looks like code when I go to the phpGroupWare URL</H2>
|
|
|
|
|
|
|
|
|
|
<P>This is often because you have php3 installed, which does not map <CODE>.php</CODE> to the PHP engine.
|
|
|
|
|
<P>For PHP3:
|
|
|
|
|
<HR>
|
|
|
|
|
<PRE>
|
|
|
|
|
AddType application/x-httpd-php3 .php3 .php
|
|
|
|
|
</PRE>
|
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
|
|
For PHP4:
|
|
|
|
|
<HR>
|
|
|
|
|
<PRE>
|
|
|
|
|
AddType application/x-httpd-php .php3 .php
|
|
|
|
|
</PRE>
|
|
|
|
|
<HR>
|
|
|
|
|
<H2><A NAME="s6">6. About this document</A></H2>
|
|
|
|
|
|
|
|
|
|
<H2>6.1 New versions </H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<P>The newest version of this document can be found on our website
|
|
|
|
|
<A HREF="http://www.phpgroupware.org">http://www.phpgroupware.org</A> as SGML source, HTML, or TEXT.
|
2000-09-27 17:10:44 +02:00
|
|
|
<H2>6.2 Comments </H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<P>Comments on this HOWTO should be directed to the phpGroupWare developers mailing list
|
|
|
|
|
<A HREF="mailto:phpgroupware-developers@lists.sourceforge.net">phpgroupware-developers@lists.sourceforge.net</A>.
|
|
|
|
|
<P>To subscribe, go to
|
2000-09-27 17:10:44 +02:00
|
|
|
<A HREF="http://sourceforge.net/mail/?group_id=7305">http://sourceforge.net/mail/?group_id=7305</A><H2>6.3 History </H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<P>This document was started by Joseph Engo and reworked by Dan Kuykendall.
|
2000-09-27 17:10:44 +02:00
|
|
|
<H2>6.4 Version History </H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<P>Old Version
|
|
|
|
|
<P>
|
|
|
|
|
<UL>
|
|
|
|
|
<LI>Created by Jengo, wasn't in SGML HOWTO format.</LI>
|
|
|
|
|
</UL>
|
|
|
|
|
<P>v1.0 (July 6, 2000)
|
|
|
|
|
<P>
|
|
|
|
|
<UL>
|
|
|
|
|
<LI>Built proper SGML version.</LI>
|
|
|
|
|
<LI>Included the FAQ.</LI>
|
|
|
|
|
<LI>Other minor additions.</LI>
|
|
|
|
|
</UL>
|
2000-09-28 17:08:47 +02:00
|
|
|
<P>v1.1 (September 27-29, 2000) - blinky
|
2000-09-27 17:10:44 +02:00
|
|
|
<P>
|
|
|
|
|
<UL>
|
|
|
|
|
<LI>Added Testing Install section</LI>
|
|
|
|
|
<LI>Added Trouble-shooting section</LI>
|
|
|
|
|
<LI>Added description of application installation</LI>
|
2000-09-28 17:08:47 +02:00
|
|
|
<LI>Changes for the new setup program</LI>
|
2000-09-27 17:10:44 +02:00
|
|
|
</UL>
|
|
|
|
|
<H2>6.5 Copyrights and Trademarks </H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<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>A copy of the license is available at
|
|
|
|
|
<A HREF="http://www.gnu.org/copyleft/fdl.txt">GNU Free Documentation License</A>.
|
2000-09-27 17:10:44 +02:00
|
|
|
<H2>6.6 Acknowledgments and Thanks </H2>
|
2000-08-18 05:24:22 +02:00
|
|
|
|
|
|
|
|
<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.
|
|
|
|
|
</BODY>
|
|
|
|
|
</HTML>
|
