forked from extern/egroupware
328 lines
13 KiB
Plaintext
328 lines
13 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<!-- LinuxDoc file was created by hand by <Dan Kuykendall> 7 July 2000 -->
|
|
<article>
|
|
<title>
|
|
phpGroupWare HOWTO
|
|
</title>
|
|
<author>
|
|
Joseph Engo <jengo@phpgroupware.org>,
|
|
Dan Kuykendall <dan@kuykendall.org>
|
|
</author>
|
|
<date>
|
|
v1.1, 28 September 2000
|
|
</date>
|
|
<abstract>
|
|
<!-- $Id$ -->
|
|
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 available 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 preferred.
|
|
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+ and/or qmail 1.03 for POP3 access
|
|
</itemize>
|
|
|
|
We have reports of it working on Windows NT and OS/2, and using Oracle as the database.
|
|
</p>
|
|
<sect1>Obtaining phpGroupWare
|
|
<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.
|
|
<sect2>Released Versions
|
|
<p>
|
|
The downloads section on the <url url="http://www.phpgroupware.org/"> site
|
|
contains links to the most recent releases, and several mirror sites
|
|
for the releases.
|
|
</p>
|
|
<sect2>Developer's version from CVS
|
|
<p>
|
|
If you have never used CVS, you may want to read through the doucmentation
|
|
found at <url url="http://www.cvshome.org/">.
|
|
The CVS pages for the core and apps projects can be found at
|
|
<url url="http://sourceforge.net/cvs/?group_id=7305" name="phpGroupWare Core CVS">, and
|
|
<url url="http://sourceforge.net/cvs/?group_id=9787" name="phpGroupWare Apps CVS">.
|
|
Follow the directions for <bf>Anonymous CVS access</bf> and you should
|
|
have the most recent development copy of phpGroupWare in no time.
|
|
</p>
|
|
|
|
<sect1>Installing on 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>
|
|
<sect1>Configure phpGroupWare
|
|
<p>
|
|
Copy the <tt>header.inc.php.sample</tt> file to
|
|
<tt>header.inc.php</tt> and edit the file, following the
|
|
directions in the comments.
|
|
<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
|
|
<tt>header.inc.php</tt>. Setup will attempt to determine what version
|
|
of the phpGroupWare database you have installed, and upgrade to the most recent
|
|
version.
|
|
|
|
<bf>NOTE:</bf>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!
|
|
|
|
If you get no error messages, continue on to phpgroupware/setup/config.php
|
|
to configure phpGroupWare to your system.
|
|
<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 disable cron_apps in the admin -> applications section
|
|
to clean out the sessions table during login and logout.
|
|
<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>
|
|
|
|
<sect>Testing the install
|
|
<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 with administrative privileges and
|
|
delete the old one.
|
|
</p>
|
|
<sect>Installing additional applications
|
|
<p>
|
|
Once you have the core phpGroupWare install up and running,
|
|
you may want to download and install additional applications.
|
|
|
|
You should consult any <tt>README</tt> or <tt>INSTALL</tt>
|
|
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 <tt>lang.sql</tt>)
|
|
|
|
You install the new application within the phpGroupWare install tree by
|
|
copying the application directory into the phpGroupWare install location,
|
|
and enabling the application through the Administration page.
|
|
|
|
For example, this is the process to install the
|
|
Headlines application (see <url url="http://sourceforge.net/phpgwapps/"> for
|
|
more on this and other applications).
|
|
<itemize>
|
|
<item>Download the .tar.gz file for the application, or check out the source
|
|
with cvs with
|
|
<verb>export CVSROOT=':pserver:anonymous@cvs.phpgroupware.sourceforge.net:/cvsroot/phpgwapps'
|
|
cvs login (just hit enter if prompted for a password)
|
|
cvs co headlines</verb>
|
|
|
|
<item>Move the <tt>headlines</tt> directory into your phpGroupWare
|
|
install directory.
|
|
|
|
<item>Log into phpGroupWare as an administrative user, and go to the Administration page.
|
|
|
|
<item>In the first section, choose the <tt>Applications</tt> link
|
|
|
|
<item>Click on add, and fill in the form.
|
|
<descrip>
|
|
<tag/Application name/ should be identical to the name
|
|
of the directory you moved into the phpGroupWare install, in this case use <tt>headlines</tt>
|
|
<tag/Application Title/this is shown in the navigation bar and other places to refer to the
|
|
new application. Enter <tt>Headlines</tt> for this example.
|
|
<tag/Enabled/This can be used to disable an application for all users temporially. You
|
|
should normal check the box to enable the application.
|
|
</descrip>
|
|
<item>Back in the Administration page, you need to enable the application for specific users
|
|
or user groups by editing them, and checking the new <tt>Headlines</tt> box that appears
|
|
in the middle of the account editing page.
|
|
<item>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.
|
|
<item>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.
|
|
</itemize>
|
|
</p>
|
|
<sect>Trouble-shooting
|
|
<p>
|
|
<bf>WARNING!</bf> 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.
|
|
|
|
The phpGroupWare developers can often be seen hanging out in #phpGroupWare
|
|
on irc.openprojects.net if you require real-time help.
|
|
|
|
Also check the FAQ in this directory for additional common questions,
|
|
it is available as FAQ.sgml, FAQ.txt and FAQ.html
|
|
|
|
<sect1>I get "Unable to open mailbox" when using the email application
|
|
<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.
|
|
|
|
An preference page to edit the email settings is being developed, and should
|
|
appear shortly after the first beta release.
|
|
</p>
|
|
|
|
<sect1>It seems to hang when I try to read my mail
|
|
<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.
|
|
|
|
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.
|
|
|
|
You can either clean up your mailbox with another mail program, or
|
|
add the line
|
|
<code>
|
|
set_time_limit(0);
|
|
</code>
|
|
to the top of the inc/phpgwapi/phpgw_msg_pop3.inc.php file, just before
|
|
the line <verb>class msg extends msg_common</verb>
|
|
|
|
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.
|
|
</p>
|
|
|
|
<sect1>When I log in I see the directory listing instead of a web page
|
|
<P>If you are using Apache, this often means you need to add
|
|
<tt>.php</tt> to the <tt>DirectoryIndex</tt> line in your httpd.conf file.
|
|
|
|
For example:
|
|
<code>
|
|
DirectoryIndex index.php index.php3 index.html index.htm index.cgi
|
|
</code>
|
|
</p>
|
|
<sect1>I get garbage that looks like code when I go to the phpGroupWare URL
|
|
<P>This is often because you have php3 installed, which does not map <tt>.php</tt> to the PHP engine.
|
|
|
|
For PHP3:
|
|
<code>
|
|
AddType application/x-httpd-php3 .php3 .php
|
|
</code>
|
|
For PHP4:
|
|
<code>
|
|
AddType application/x-httpd-php .php3 .php
|
|
</code>
|
|
</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>
|
|
<p>
|
|
v1.1 (September 27-29, 2000) - blinky
|
|
</p>
|
|
<p>
|
|
<itemize>
|
|
<item>Added Testing Install section
|
|
<item>Added Trouble-shooting section
|
|
<item>Added description of application installation
|
|
<item>Changes for the new setup program
|
|
</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>Acknowledgments 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>
|