forked from extern/egroupware
595 lines
19 KiB
Plaintext
595 lines
19 KiB
Plaintext
phpGroupWare HOWTO
|
||
Joseph Engo <jengo@phpgroupware.org>, Dan Kuykendall
|
||
<dan@kuykendall.org>, Stephen Brown <blinky@phpgroup-
|
||
ware.net>
|
||
v1.3, 17 October 2000
|
||
|
||
This document explains how to install and configure phpGroupWare.
|
||
______________________________________________________________________
|
||
|
||
Table of Contents
|
||
|
||
|
||
1. Introduction
|
||
|
||
1.1 What is phpGroupWare and why should I use it?
|
||
|
||
2. Installation
|
||
|
||
2.1 Requirements
|
||
2.2 Tested Systems
|
||
2.3 Obtaining phpGroupWare
|
||
2.3.1 Released Versions
|
||
2.3.2 Developer's version from CVS
|
||
2.4 Installing on Tested Systems
|
||
2.5 Create a database and user for phpGroupWare
|
||
2.5.1 Adding DB and users in MySQL
|
||
2.5.2 PostgereSQL install
|
||
2.6 Configure phpGroupWare
|
||
|
||
3. Testing the install
|
||
|
||
4. Installing additional applications
|
||
|
||
5. Trouble-shooting
|
||
|
||
5.1 I get "Unable to open mailbox" when using the email application
|
||
5.2 It seems to hang when I try to read my mail
|
||
5.3 When I log in I see the directory listing instead of a web page
|
||
5.4 I get garbage that looks like code when I go to the phpGroupWare URL
|
||
|
||
6. Known working systems
|
||
|
||
6.1 Seek3r has tested
|
||
6.2 blinky has tested
|
||
6.3 Jengo has tested
|
||
|
||
7. About this document
|
||
|
||
7.1 New versions
|
||
7.2 Comments
|
||
7.3 History
|
||
7.4 Version History
|
||
7.5 Copyrights and Trademarks
|
||
7.6 Acknowledgments and Thanks
|
||
|
||
|
||
______________________________________________________________________
|
||
|
||
11.. IInnttrroodduuccttiioonn
|
||
|
||
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.
|
||
|
||
It should run on all systems where PHP is available and currently
|
||
supports MySQL and PostgreSQL.
|
||
11..11.. WWhhaatt iiss pphhppGGrroouuppWWaarree aanndd wwhhyy sshhoouulldd II uussee iitt??
|
||
|
||
phpGroupWare is:
|
||
|
||
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.
|
||
|
||
|
||
You should use it if:
|
||
|
||
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?
|
||
|
||
22.. IInnssttaallllaattiioonn
|
||
|
||
22..11.. RReeqquuiirreemmeennttss
|
||
|
||
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.
|
||
|
||
22..22.. TTeesstteedd SSyysstteemmss
|
||
|
||
Known compatible software
|
||
|
||
+o PHP 3.0.15+ or PHP 4.0.x (preferred)
|
||
|
||
+o Apache 1.3.x
|
||
|
||
+o MySQL 3.22.25 or greater
|
||
|
||
+o MySQL 3.23.10 or greater
|
||
|
||
+o Courier IMAP 0.33+ for IMAP (optionally with vmailmgr)
|
||
|
||
+o qmail 1.03 for SMTP and POP
|
||
|
||
+o sendmail for SMTP
|
||
|
||
Example configurations that the CVS versions have been up and running
|
||
on are listed at the end of this document. We have reports of
|
||
phpGroupWare working on Windows NT and OS/2, and using Oracle as the
|
||
database.
|
||
|
||
22..33.. OObbttaaiinniinngg pphhppGGrroouuppWWaarree
|
||
|
||
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.
|
||
|
||
22..33..11.. RReelleeaasseedd VVeerrssiioonnss
|
||
|
||
The downloads section on the <http://www.phpgroupware.org/> site
|
||
contains links to the most recent releases, and several mirror sites
|
||
for the releases.
|
||
|
||
|
||
|
||
22..33..22.. DDeevveellooppeerr''ss vveerrssiioonn ffrroomm CCVVSS
|
||
|
||
If you have never used CVS, you may want to read through the
|
||
doucmentation found at <http://www.cvshome.org/>. The CVS pages for
|
||
the core and apps projects can be found at phpGroupWare Core CVS
|
||
<http://sourceforge.net/cvs/?group_id=7305>, and phpGroupWare Apps CVS
|
||
<http://sourceforge.net/cvs/?group_id=9787>. Follow the directions
|
||
for AAnnoonnyymmoouuss CCVVSS aacccceessss and you should have the most recent
|
||
development copy of phpGroupWare in no time.
|
||
|
||
22..44.. IInnssttaalllliinngg oonn TTeesstteedd SSyysstteemmss
|
||
|
||
After you have met the additional software requirements (working DB,
|
||
POP3/IMAP server, and PHP), unpack the tarball in the html directory
|
||
of your webserver. (eg, /home/httpd/html) If you want the phpGroupWare
|
||
install to appear at a URL other than http://localhost/phpgroupware
|
||
now is the time to rename the directory or move it around under your
|
||
document root.
|
||
|
||
22..55.. CCrreeaattee aa ddaattaabbaassee aanndd uusseerr ffoorr pphhppGGrroouuppWWaarree
|
||
|
||
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).
|
||
|
||
Note the host the database engine is on, user, password and database
|
||
name, you will need them soon.
|
||
|
||
22..55..11..
|
||
|
||
AAddddiinngg DDBB aanndd uusseerrss iinn MMyySSQQLL
|
||
|
||
The quick stepse to get going on mysql are as follows (please consult
|
||
the offical MySQL documentation for the details).
|
||
|
||
mysqladmin create phpgroupware - creates the blank database
|
||
|
||
Go into the mysql command line utility with mysql mysql or use a tool
|
||
like phpMyAdmin to update the permission tables. It is recommended
|
||
that you add a user with no permissions, then explicitly grant the
|
||
user access to the phpgroupware database. The following SQL is an
|
||
example:
|
||
|
||
insert into users(Host,User,Password) values('localhost','phpgwuser',PASSWORD('somethinghardtoguess');
|
||
insert into db(Host,DB,User,Select_priv,Insert_priv,Update_priv,Delete_priv,Create_priv,Drop_priv,Alter_priv)
|
||
values('localhost','phpgroupware','phpgwuser','Y','Y','Y','Y','Y','Y','Y')
|
||
|
||
|
||
|
||
you must then reload the grant tables with mysqladmin reload or
|
||
refresh privledges from the mysql utility.
|
||
|
||
22..55..22..
|
||
|
||
PPoossttggeerreeSSQQLL iinnssttaallll
|
||
|
||
This is from gnrfan but has yet to be updated for the recent version
|
||
of phpGroupWare, although it should get you started.
|
||
|
||
To start the postmaster just type at the console: $postmaster -i -D
|
||
/home/[username]/[dataDir] Now if there is an error then is no datadir
|
||
intitiated (assuming that postgreSQL is installed). To do that you
|
||
have to use initdb to create the dataDIR. Please look in the
|
||
documentation of posgreSQL or the manual page for initdb for details.
|
||
|
||
|
||
If you have not encountered any error than you are ready to roll. Now
|
||
create a database which will be used by the phpGroupWare. To do that
|
||
type at the console: $createdb phpgroupware assumming that you would
|
||
name the database phpgroupware.
|
||
|
||
22..66.. CCoonnffiigguurree pphhppGGrroouuppWWaarree
|
||
|
||
Copy the header.inc.php.sample file to header.inc.php and edit the
|
||
file, following the directions in the comments.
|
||
|
||
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 header.inc.php. Setup will attempt to determine what
|
||
version of the phpGroupWare database you have installed, and upgrade
|
||
to the most recent version.
|
||
|
||
NNOOTTEE::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.
|
||
|
||
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 chown nobody.nobody and chmod 700 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.
|
||
|
||
If you do not have access to root, create this file and run it.
|
||
|
||
<?php
|
||
if (mkdir("/path/to/temp/directory",0700)) {
|
||
echo "Directory created successfully";
|
||
} else {
|
||
echo "Error creating directory";
|
||
}
|
||
|
||
|
||
If you have access to cron, you may want to setup the files in the
|
||
cron directory.
|
||
|
||
stalesessions.pl - There are 2 reasons for this file.
|
||
|
||
+o Users always forget to logout. This way the session doesn't sit
|
||
around forever, creating a possible security risk.
|
||
|
||
+o The email system requires plain text passwords which are stored in
|
||
the sessions table.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
33.. TTeessttiinngg tthhee iinnssttaallll
|
||
|
||
If your config is setup properly you can now login. Point your
|
||
browser to the installed location and login with the username demo and
|
||
the password is 1234
|
||
At this point it would be a good idea to create a new user with
|
||
administrative privileges and delete the old one.
|
||
|
||
44.. IInnssttaalllliinngg aaddddiittiioonnaall aapppplliiccaattiioonnss
|
||
|
||
Once you have the core phpGroupWare install up and running, you may
|
||
want to download and install additional applications.
|
||
|
||
You should consult any README or INSTALL 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 lang.sql)
|
||
|
||
You install the new application within the phpGroupWare install tree
|
||
by placing the application directory under the root phpGroupWare
|
||
directory, and enabling the application through the Administration
|
||
page.
|
||
|
||
For example, this is the process to install the Headlines application
|
||
(see <http://sourceforge.net/phpgwapps/> for more on this and other
|
||
applications).
|
||
|
||
+o Download the .tar.gz file for the application, or check out the
|
||
source with cvs with
|
||
|
||
export CVSROOT=':pserver:anonymous@cvs.phpgroupware.sourceforge.net:/cvsroot/phpgwapps'
|
||
cvs login (just hit enter if prompted for a password)
|
||
cvs co headlines
|
||
|
||
|
||
|
||
+o Move the headlines directory into your phpGroupWare install
|
||
directory.
|
||
|
||
+o Log into phpGroupWare as an administrative user, and go to the
|
||
Administration page.
|
||
|
||
+o In the first section, choose the Applications link
|
||
|
||
+o Click on add, and fill in the form.
|
||
|
||
AApppplliiccaattiioonn nnaammee
|
||
should be identical to the name of the directory you moved into
|
||
the phpGroupWare install, in this case use headlines
|
||
|
||
AApppplliiccaattiioonn TTiittllee
|
||
this is shown in the navigation bar and other places to refer to
|
||
the new application. Enter Headlines for this example.
|
||
|
||
EEnnaabblleedd
|
||
This can be used to disable an application for all users
|
||
temporially. You should normal check the box to enable the
|
||
application.
|
||
|
||
+o Back in the Administration page, you need to enable the application
|
||
for specific users or user groups by editing them, and checking the
|
||
new Headlines box that appears in the middle of the account editing
|
||
page.
|
||
|
||
+o 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.
|
||
|
||
+o 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.
|
||
|
||
55.. TTrroouubbllee--sshhoooottiinngg
|
||
|
||
WWAARRNNIINNGG!! 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
|
||
|
||
|
||
55..11.. II ggeett ""UUnnaabbllee ttoo ooppeenn mmaaiillbbooxx"" wwhheenn uussiinngg tthhee eemmaaiill aapppplliiccaattiioonn
|
||
|
||
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 second beta release.
|
||
|
||
55..22.. IItt sseeeemmss ttoo hhaanngg wwhheenn II ttrryy ttoo rreeaadd mmyy mmaaiill
|
||
|
||
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
|
||
|
||
______________________________________________________________________
|
||
set_time_limit(0);
|
||
______________________________________________________________________
|
||
|
||
|
||
to the top of the inc/phpgwapi/phpgw_msg_pop3.inc.php file, just
|
||
before the line
|
||
|
||
class msg extends msg_common
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
55..33.. WWhheenn II lloogg iinn II sseeee tthhee ddiirreeccttoorryy lliissttiinngg iinnsstteeaadd ooff aa wweebb ppaaggee
|
||
|
||
If you are using Apache, this often means you need to add .php to the
|
||
DirectoryIndex line in your httpd.conf file.
|
||
|
||
For example:
|
||
|
||
______________________________________________________________________
|
||
DirectoryIndex index.php index.php3 index.html index.htm index.cgi
|
||
______________________________________________________________________
|
||
|
||
|
||
|
||
55..44.. II ggeett ggaarrbbaaggee tthhaatt llooookkss lliikkee ccooddee wwhheenn II ggoo ttoo tthhee pphhppGGrroouuppWWaarree
|
||
UURRLL
|
||
|
||
This is often because you have php3 installed, which does not map .php
|
||
to the PHP engine.
|
||
|
||
For PHP3:
|
||
|
||
______________________________________________________________________
|
||
AddType application/x-httpd-php3 .php3 .php
|
||
______________________________________________________________________
|
||
|
||
|
||
For PHP4:
|
||
|
||
______________________________________________________________________
|
||
AddType application/x-httpd-php .php3 .php
|
||
______________________________________________________________________
|
||
|
||
|
||
|
||
66.. KKnnoowwnn wwoorrkkiinngg ssyysstteemmss
|
||
|
||
A rough description of some of the hardware and software the
|
||
developers have used to develop phpGroupWare on, oh have confirmed
|
||
working reports from people in IRC.
|
||
|
||
66..11..
|
||
|
||
SSeeeekk33rr hhaass tteesstteedd
|
||
|
||
phpGroupWare.org runs: Red Hat 6.2,
|
||
Apache/1.3.12,PHP/4.0.2,mod_perl/1.21,MySQL 3.23.10-alpha,Courier-IMAP
|
||
0.33+ with qmail 1.03
|
||
|
||
66..22..
|
||
|
||
bblliinnkkyy hhaass tteesstteedd
|
||
|
||
phpGroupWare.net runs: Red Hat 6.2,Apache/1.3.14 PHP/4.0.3pl1
|
||
mod_ssl/2.7.1 OpenSSL/0.9.6 PHP4.03.pl1,MySQL 3.23.10-alpha,qmail 1.03
|
||
|
||
dev boxes are variants on: Red Hat 7.0,mysql-3.23.22-6 (from RH7 RPM),
|
||
and Sendmail, Courier, or qmail+courier IMAP depending on mood.
|
||
|
||
66..33..
|
||
|
||
JJeennggoo hhaass tteesstteedd
|
||
|
||
main test box: Red Hat 6.2,Apache/1.3.12,PHP 3.0.16,PostgreSQL
|
||
7.2,Sendmail (from RH6.2)
|
||
|
||
|
||
laptop is rh 6.1, apache 1.3.?, MySQL and PostgreSQL 7.0 w/ PHP
|
||
3.0.16, its a P-90 w/ 40 mb ram and a 800 mb hd
|
||
|
||
|
||
Also, confirmation through IRC of phpGroupware working on Win2k with
|
||
IIS5.0, PHP4.0.2 and MySQL just recently
|
||
|
||
77.. AAbboouutt tthhiiss ddooccuummeenntt
|
||
|
||
77..11.. NNeeww vveerrssiioonnss
|
||
|
||
The newest version of this document can be found on our website
|
||
<http://www.phpgroupware.org> as SGML source, HTML, or TEXT.
|
||
|
||
77..22.. CCoommmmeennttss
|
||
|
||
Comments on this HOWTO should be directed to the phpGroupWare
|
||
developers mailing list phpgroupware-developers@lists.sourceforge.net
|
||
<mailto:phpgroupware-developers@lists.sourceforge.net>.
|
||
|
||
To subscribe, go to http://sourceforge.net/mail/?group_id=7305
|
||
<http://sourceforge.net/mail/?group_id=7305>
|
||
|
||
77..33.. HHiissttoorryy
|
||
|
||
This document was started by Joseph Engo and reworked by Dan
|
||
Kuykendall.
|
||
|
||
77..44.. VVeerrssiioonn HHiissttoorryy
|
||
|
||
Old Version
|
||
|
||
|
||
+o Created by Jengo, wasn't in SGML HOWTO format.
|
||
|
||
v1.0 (July 6, 2000)
|
||
|
||
|
||
+o Built proper SGML version.
|
||
|
||
+o Included the FAQ.
|
||
|
||
+o Other minor additions.
|
||
|
||
v1.1 (September 27-29, 2000) - blinky
|
||
|
||
|
||
+o Added Testing Install section
|
||
|
||
+o Added Trouble-shooting section
|
||
|
||
+o Added description of application installation
|
||
|
||
+o Changes for the new setup program
|
||
|
||
v1.2 (Early October 2000) - blinky
|
||
|
||
|
||
+o Info about creatign MySQL DB and user
|
||
|
||
+o Partial PostgreSQL info from gnrfan
|
||
|
||
77..55.. CCooppyyrriigghhttss aanndd TTrraaddeemmaarrkkss
|
||
|
||
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
|
||
|
||
A copy of the license is available at GNU Free Documentation License
|
||
<http://www.gnu.org/copyleft/fdl.txt>.
|
||
|
||
77..66.. AAcckknnoowwlleeddggmmeennttss aanndd TThhaannkkss
|
||
|
||
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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|