extern/egroupware
1
0
Fork 1
mirror of https://github.com/EGroupware/egroupware.git synced 2024-12-27 00:58:55 +01:00
Code Issues Packages Projects Releases Wiki Activity
703b1c2553
egroupware/doc/HOWTO.txt
sjb4891 4119c27bb4 Minor fixes before 0.9.2 release
2000-10-18 05:42:26 +00:00

595 lines
19 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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.
Reference in New Issue View Git Blame Copy Permalink