Setting up more.groupware
From MGWiki
Setting up more.groupware is described in this and the following chapters. Generally you should read this chapter, as it tells you about some basic requirements and skills you should have available and ready. Then you only need to read one of the following chapters, depending on the operating system you want to install more.groupware on.
Contents |
Requirements
To successfully install more.groupware you need at least the following software packages on your machine, regardless of the operating system in use.
- A webserver (Apache is recommended)
- PHP 4.2.0 or later with XML support
- A database server (MySQL 3.23.x/4.x or PostgreSQL 7.x)
- PHP session auto start must be disabled!
It is necessary to have a . (dot) in your PHP include_path. Look at php.ini to check this.
If want to create GANTT charts in the projects module, you will need support for the GD library in your PHP installation. On windows this should only be a matter of uncommenting extension=php_gd.dll in your php.ini, on most Linux distributions it similar.
You do not need PDF or IMAP support compiled into PHP for the current releases, nor do you need XML DOM. We handle those needs with PHP-only libraries. It does not harm to have those things compiled into PHP, though.
We intend to support more databases in the future. Right now MySQL works best, and PostgreSQL support is getting better (the core modules should work). Other databases will follow later.
When you want to run more.groupware on MySQL 4.1.x, watch out when reating the database. Do not set the default charset/collation to utf8, as then varchar fields default to utf8. And the max length of a primary key is 500 bytes, not characters. This will cause problems with admin2, as some fields are longer and used as primary key.
You should try to run more.groupware with register_globals disabled, if it doesn't work, it's a bug. The same is true for magic_quotes_gpc and magic_quotes_runtime, both should be off. Those are not strict requirements, though.
The setup will check all those (and some more) things, and tell you when something is wrong or missing.
Upgrade
When upgrading from one version of more.groupware to the next it is recommended that you do so via a clean installation. To upgrade otherwise requires an advanced knowledge of SQL and a lot of "hacking" to your database.
An automatic upgrade function is being worked on, and as soon as it is available it will be released, but until then we highly recommend you re-install from a clean empty database.
If you want to try an upgrade, you should look at the upgrade instructions in the appendix.
Getting more.groupware
Whether you install on Windows, Unix or Mac - you need to get the software somehow. This will show you the different ways to download more.groupware.
Downloading more.groupware releases
This is the recommended way of downloading more.groupware for most people. You can either go to the download page at moregroupware.org or use the files section at sourceforge.net .
Either way, there are two flavours available, ZIP archives and gzipped TAR archives. You should download the ZIP archive only if you want to install on Windows, in all other cases you should go for the TAR archive. Note that most Windows software (including WinZip) can handle TAR archives just as well. The flavours are identical except for the archive format and the format of the line ends inside the source files (\n for TAR, \r\n for ZIP).
Downloading more.groupware snapshots
If you want to live on the bleeding edge, using the latest code available, but don't want to (or can't) use CVS directly to get the sources, download one of the nightly snapshots. They are available at the snapshots page at moregroupware.org. Be careful though, unless we recommend to do this, you are on your own with any problems that might arise from using snapshots.
The longer ago the last release took place, the more you might want to use a snapshot. But you might want to know what you are doing.
Snapshots are only available as gzipped TAR archives. Note that most Windows software (including WinZip) can handle TAR archives just as well.
Downloading more.groupware from CVS
Directly downloading more.groupware from the CVS (Concurrent Versions System, see http://www.cvshome.org/ ) repository gives you real-time access to the latest and greatest code available. You should note though, that it might be even buggier than the snapshots! You still want to do it via CVS? Here we go... the SourceForge.net CVS page for more.groupware.
Preparing the more.groupware setup
After you downloaded more.groupware as per the instructions above, make the unpacked more.groupware root folder to writable for the webserver and create a database user for use with more.groupware. You can create a database now, or let setup do this - your choice.
The setup process
After you have unpacked more.groupware and done the necessary preparations according to the previous chapters, you are ready tu run the web-based setup procedure. It is described in full detail in this chapter. After you are through with this, check back with the platform specific instructions to make sure you don't miss anything you need to do to conclude the installation. Then read the chapter on Securing your more.groupware setup!
Start your web browser and open the URL http://localhost/moregroupware/index.php (or http://your.doma.in/moregroupware/index.php if you run setup at a remote computer).
As you don't have run the setup yet you will get an error message:
Use the "run setup" link to start the setup process. If you want to read this manual you can choose the "look at the manual" link. If you choose to run the setup you will get the following setup screen:
Choose the language you want to use for the installation. What you choose here, will be the default language for your installation, i.e. the login screen will default to this language as well. After you have done the choice you must press refresh to update the output to your chosen language. Setup shows error messages and information if needed. If you want those messages to appear as popup windows, select 'Yes' in the drop-down box labeled 'Use javascript for errors'.
Now click Next to go to step 2:
Hopefully your computer passes the system check. If not you have to do the necessary changes in system settings before you try to run the setup again. Press Next if everything is ok.
Now it's time for some real configuration:
The settings you can or need to set here have the following meaning:
- Database Software
- This is the type of database you use. Only MySQL and PostgreSQL work by now, but we want to support more database systems in the future. Set this to the software you use. You only get options your PHP supports!
- Database Hostname / IP
- The machine name or IP address the database runs on. If this is the same machine as the webserver, use 'localhost'. Otherwise type the name or IP, using the IP might improve the performance in extreme situations (because the name doesn't need to be resolved). In case of PostgreSQL as database system, just supplying user and password, with leaving the hostname blank is possible as well.
- Database User
- The database user you created (or that has been created for you) for moregroupware. This is the same user you might have created in previous steps during the installation.
- Database Password
- The password given to the database user you used above.
- Name of database
- The database name you defined when creating an empty database for more.groupware.
- Attempt to create database
- If you haven't already created the database you want to use, you can have setup create it. Checking this option will show two more fields for username and password of a user that can create databases.
- URL to moregroupware root
- This is the URL that points to your more.groupware installation. It should be guessed correctly in most cases, but check anyway, just to make sure.
- Skip URL check
- If setup claims the root URL is not correct, but you are sure it is, you can skip the check. Do this at your own risk...
- Use dynamic URL detection
- If your server can be accessed by different names (e.g. depending on whether you access it from inside or from outside of your LAN), you need to check this. It will use the hostname supplied by the browser (as aprt of the request) instead of a hardcoded one. This will only work with HTTP/1.1, but this should be standard nowadays.
- Force use of SSL
- You can check this to have more.groupware redirect to a SSL connection whenever it detects an unencrypted connection.
- Session name
- This is the name of the session that will be used. PHP defaults to PHPSESSION, which of course may lead to different sessions using the same name. So we choose something different, and you can make it unique if you like.
- Use DB for session storage
- Usually the session data is stored in files on the server's file system. Optionally you can have more.groupware store the session data in the database.
- System path to moregroupware
- This is the path to the directory you unpacked more.groupware into. Should be guessed correctly, check it anyway, just to make sure.
- Authentication method
- You can authenticate the more.groupware users either through LDAP, the database or NTLM/htaccess. Using the database is the most used and most widely tested method, so it's a safe bet. If you have your users in LDAP (OpenLDAP or Active Directory) anyway, go this way. In a Windows-based LAN NTLM might be the best choice.
- Don't submit passwords with MD5 encryption
- Passwords can be submitted using a MD5 encryption. They are hashed on the client using JavaScript, to avoid sending cleartext passwords over the net. This feature is switched off automatically if no JS is available on the client, but you may completely disable it here. Important: If you want real security, use SSL! If one captures the hashed password, it is as easy to break into your system, as it would be with a cleartext password!
- Admin password
- Choose the intial password for the admin user that get's created.
Press Next to go to step 4:
Nothing to do here if you have chosen authentication of users via SQL or NTLM/htaccess. Press next in this case.
If you selected LDAP as authentication method, you'll see this:
- Directory type
- Select your directory type, either OpenLDAP or Active Directory.
- LDAP Host
- The host to connect to for LDAP queries. If your choice is AD, use the Host IP)
- LDAP Base
- If your choice is AD, use the domain in format "DC=mydomain,DC=com", without slashes
- LDAP userid
- The user you want to use to connect to the directory server. If your choice is AD, use any user who´s registered in Active Directory in format user@mydomain.com
- LDAP root password
- The password given to the user you entered in the previous field.
- LDAP suffix
- If your choice is AD, use "@mydomain.com", without slashes
- Create Account on LDAP login
- You can select 'Yes' here to have more.groupware automatically create accounts for users who can be authenticated successfully through LDAP. If you select 'No', you need to create those accounts manually. I recommend you to use 'Yes'
After entering the needed values, click 'Next' to continue with the module installation.
Press next after you read the provided information.
Hopefully you get the message above which tells you that the installation was successfully. If not you can choose view log to see why the installation failed. There you should get enough information about what went wrong, and why. Try to fix the problems, and restart the setup.
Now comes your first login. Press login or point your browser manually to http://localhost/moregroupware/index.php for doing your first login (if you want to use NTLM authentication, use http://localhost/moregroupware/index_ntlm.php instead). Use user "admin" and your chosen password.
Securing your moregroupware setup
Here are some hints and remarks on security in moregroupware.
- Check the rights on your installation files and folders. No directories except data_store, data_cache and the templates_c folder need to be writable by the webserver. And those directories need to be writable only by the webserver, there is no need to have them world-writable.
- The data_store and data_cache folders may contain files that are not meant to be accessible from outside of more.groupware. Thus you should restrict access to them. .htaccess files are already present, but you should check if they work. Depending on your webservers configuration the usage of .htaccess files may be restricted. If you are not using the Apache webserver, take similar measures for your setup.
Additionally you should make them only accessible to the webserver user and/or group on filesystem level, by changing folder access permissions accordingly, if they allow access to others. - If you are concerned about cross-site scripting attacks, you should remember that those are almost always used to hijack a session. Because you can lock your session to an IP address in more.groupware (this is true by default), having access to the session ID doesn't give you access to the session in most cases.
And you need a valid login to the system to be able to inject such malicious content. And if you can't trust your users, secure software is only worth that much. - You may delete the setup/ folder after successfully installing your moregroupware.
- Think about the scripts in the scripts/ folder of moregroupware, some might give others the possibility to gather information about your system, you would rather like to keep private (e.g. systeminfo.php). You should restrict access to this folder or move it elsewhere. If you don't need it's contents, you can safely delete it.
- If you use moregroupware outside of a closed network environment, consider using SSL. moregroupware is completely SSL-transparent, i.e. you can use it without any changes on an SSL-enabled webserver.
- There is no need to worry about the sess_* files in your webserver's /tmp directory, as long as these files are only readable by the user your webserver runs as. You don't need to delete them as well, PHP will do this automatically with a given probability after a session expired. See the PHP manual for more information.
We are trying hard to make the moregroupware code itself as secure as possible, by checking all input data, etc.
Troubleshooting
If you get problems with your more.groupware installation you can visit the more.groupware website and have a look at the support page.
You can subscribe to one of the mailing lists or browse the archives, you can visit the more.groupware IRC channel (irc.freenode.net, #moregroupware) or you can submit bug reports and support requests at the more.groupware Sourceforge project page.
Remember that more.groupware is an open source project and not a commercial product! You cannot demand a very high service level from the developers as they are doing all the work in their limited spare time. We try help where we can, though!
Known bugs
Webmail 2
If you try to receive big e-mails with attachements you can get a timeout like:
Fatal error: Maximum execution time of 60 seconds exceeded in c:\web\moregroupware\modules\webmail2\inc\class.pop3.inc on line 418 Fatal error: Maximum execution time of 60 seconds exceeded in c:\web\moregroupware\modules\webmail2\inc\pear.php on line 498
One dirty way to fix it is to edit /modules/webmail2/inc/class.pop3.inc. Around line 14 you should find
var $TIMEOUT = 60; // Default timeout before giving up on a network operation.
If you change from e. g. 60 to 260 you should not so easily get the timeout.
If you see memory error messages like:
Fatal error: Allowed memory size of 8388608 bytes exhauste (tried to allocate 8192 bytes) in ...
This happens because the webmail2 module downloads email from the mail server. These email can only be downloaded in one step, that means the whole email is copied to the memory and then stored on your harddisk. e.g. an email with the size of 5 MB needs about 10-15 MB in the memory.
To fix it you have to increase the memory limit in php.ini:
memory_limit = 8M ; Maximum amount of memory a script may consume (8MB)
Increase this value to '16M' (16 MB) or more (depends on the size of the emails you get, often there is a limit on the mail server [e.g 10 MB for gmx]).
If you have problems with sending and/or receiving emails with large attachments you should try to increase the values for 'post_max_size' and 'upload_max_filesize' in php.ini. Set them to a value high enough, e.g. '20M'.
General strange behavior of more.groupware
Check php.ini and the parameters below as mentioned earlier in this guide:
include_path = "." register_globals = Off session.auto_start = Off
If you see memory error messages like:
Fatal error: Allowed memory size of 8388608 bytes exhauste (tried to allocate 8192 bytes) in ...
you have to increase the memory limit in php.ini to e.g. 16 MB:
memory_limit = 16M ;
While you are editing php.ini anyway, you might want to change some more things:
display_errors = Off error_reporting = E_ALL ~ E_NOTICE log_errors = On error_log = /var/log/php.log
(make sure Apache has the rights to write to this file). This will make all erros and warnings go to a log file instead of to the screen, which solves a lot of problems already, and makes it easier to work on the remaining ones.
Login screen in stead of the data you expected: Internet Explorer 6 can behave strange together with more.groupware. Some times people have had good results with erasing temporary files from their computer. After such a clean up everything often works fine for a while.
If you get problems with the graphics, login screen in stead of that you expected etc. a solution can be to change the following line in config.inc.php:
$appconf["rooturl"] = "http://localhost/moregroupware";"
to look like this:
$appconf["rooturl"]="http://".$HTTP_SERVER_VARS["HTTP_HOST"]."/moregroupware";
Wrong URL in config.inc.php: You install more.groupware, log in and everything is ok. Another person on your network tries to login and doesn't see the right layout at the login screen (and login fails).
Solution: Go to the home directory of mgw, take a look at config.inc.php. Look for the variables:
$appconf["rooturl"] = ... $appconf["rootpath"] = ...
If $appconf["rooturl"] is something like http://localhost/moregroupware/ or http://127.0.0.1/moregroupware/ you have to replace localhost or 127.0.0.1 with your real IP address that is reachable from other computers in the net.
A solution can also be to change from:
$appconf["rooturl"] = "http://localhost/moregroupware";
to
$appconf["rooturl"]="http://".$_SERVER["HTTP_HOST"]."/moregroupware";
Additional moregroupware components
more.groupware has some addons that can optionally be used to enhance the "user experience". Setup and usage of these addons are described here.
Appointment reminder
This script is to be called via the cron daemon and sends out appointment reminders via email.
This is still very experimental and might not work at all! Hopefully this will be worked on in the future... but for now just make sure you know what you are doing if you use this.
Address queries with Mutt
This script queries the (remote) moregroupware database server for names and email addresses and returns data which Mutt (the email client) can use to display a selection menu.
This is supposed to be called by mutt. Insert set query_command = "mgwquery.sh '%s'" into your .muttrc to make this work (The script needs to be in your PATH. It it is not, provide the full path to the script).
You have to change the variables at the beginning of this file to be able to connect to the database.
To test the connection, you may afterwards call this script directly and give a single argument to it: mgwquery.sh 'a'
If this works you may use Q to query for contacts in the more.groupware database or Ctrl-t to auto-complete an address.
Moving data from TWIG to moregroupware
This converts TWIG contacts to more.groupware.
The companies are mapped to the companies table, using the company entry of TWIG as key.
All entries are mapped to contact group 1, which is Customers after installation of moregroupware. All countries are set to Germany.
Adjust your connect data, database and table names below. And make a backup before proceeding.
ALL moregroupware contact and company DATA IS DELETED BEFORE CONVERSION!
After conversion prepare to fix the sequences manually.
