WebCollab Frequently Asked Questions (FAQ)

FAQ INDEX

Setup Problems
Startup Problems
Customising WebCollab
Performance Tuning
Uploading Files
Email
Internationalisation
Security
Remote Databases
Database Types
Database Transactions
Database Backups
Translations

SETUP PROBLEMS

1. Setup program says that database can be created, but cannot write to the config file.
The web server does not/cannot have permissions to write to the config file. You need to make the config file world-writable. The config file is /config/config.php below the root directory of WebCollab. 
#chmod 666 config.php
For security, reinstate afterwards with: 
#chmod 664 config.php
2. How to upgrade from an earlier version of WebCollab?
Refer to the INSTALLATION file. Briefly, all versions are upgradable by adding the new files. Versions pre-1.40 and pre-1.60 need to have the database upgraded with the by pointing your web browser at /update.php.
3. All the documentation mentions the Apache web server. Can we use Microsoft IIS instead?
WebCollab is not tested nor supported on Microsoft IIS. That said, we have had successful reports of WebCollab running on Microsoft IIS (Windows Server 2003 and Windows Server 2000).

Here is how one Windows user got it working:

  1. PHP and Mysql were previously installed and working for other apps.
  2. Used Internet Services Manager to create website with Frontpage extensions.
  3. Unzipped Webcollab to website folder.
  4. Gave the default anonymous IUSR_servername write rights to config.php.
  5. Completed the setup page ignoring the invalid url error. I used the root user to create the database and also the user for setup.
  6. Since for some reason I couldn't get it to work for the root user I created a new user with full rights to the database. I then edited the config.php file to reflect the change of user and password.
  7. Removed the default anonymous IUSR_servername write rights to config.php.
  8. Using the Internet Services Manager I restarted IIS.
  9. Logged in and it was working.

START UP PROBLEMS

1. "Initial installation works, but logging in as admin has no effect (no error message either)."
This problem occurs with PHP 4.0.6 and lower. WebCollab will only run on PHP 4.1.0, or higher. Earlier versions of PHP do not support $_POST, $_GET or $_REQUEST global arrays, which are necessary for WebCollab to function.

(The setup program now checks for early versions of PHP and will record an error).
2. "Initial installation works, but logging in as admin gives a blank screen."
Check that PHP has your database extensions compiled in. From the command line type 'php -m':

# php -m
Running PHP 4.2.2
Zend Engine v1.2.0, Copyright (c) 1998-2002 Zend Technologies

[PHP Modules]
mysql
pgsql

[Zend Modules]

#

Look for mysql and/or pgsql as required in the modules listing that follows.

Most likely cause is that the default file for php.ini has the mysql or pgsql module line commented out. Look for lines in php.ini like this:

;extension=mysql.so
;extension=pgsql.so

Remove the semi-colon ';' from the module you want, and restart Apache.

Also - many Linux distributions have separate packages (*.rpm, *.deb, etc) for the main PHP files and the MySQL/PostgreSQL PHP support. You need to install the relevant module package as well.
3. Setup says "Your version of PHP does not have support for MySQL..." or "Your version of PHP does not have support for PostgreSQL..." and then dies.
This is the same as the problem above.
4. "Can login, but the main page is not found (404 error)."
Check that the the parameter $BASE_URL is correctly stated in config.php. Did you remember to add the trailing slash "/" as the config file says?
5. "Does WebCollab use cookies?"
Yes, if possible. Cookies are preferred for session management, but aren't reliable with all browsers.

Webcollab attempts to set a session cookie at the login. Additionally it uses encoded URI's at this stage, also for session management. If the session cookie is found to be successful (I.e. the user's browser accepts the cookie), the encoded URI's are dropped. Otherwise session management with encoded URI is continued.

The session cookie lasts only as long as the current session. It will be automatically destroyed when the browser is closed, or the user logs out.
5. "Does Magic Quotes need to be set 'on' or 'off' in php.ini?"
When magic_quotes set to 'on' in php.ini, input data is automatically feed through the addslashes() function for security. WebCollab reads the php.ini file, and applies addslashes() on input data if magic quotes is set to 'off'. The addslashes() function is important to prevent SQL injection attacks.
6. "Does Register Globals need to be 'on' in php.ini?"
Software written for early versions of PHP (prior to version 4.1.0) often requires Register Globals to properly receive input data. However for important security reasons Register Globals has defaulted to 'off' since PHP 4.2.0. WebCollab does not require Register Globals. You should leave Register Globals 'off' for better web site security, unless it is specifically required to be 'on' for other scripts.

CUSTOMISING WEBCOLLAB

1. Can the 'Done', 'Active', 'On Hold' etc, labels be changed?
Yes, all the parameters are defined in the language files in /WebCollab/lang/ They can be easily changed to suit.

Alternatively, a new customised language file can be set up and defined in /lang/language.php
2. Can the splash screen image be changed?
Yes, add the new image to /images/ and set the $SITE_IMG parameter in /config/config.php
3. Can background colours and text styles be changed?
Yes, see the style sheet /css/default.css.
4. Can external web server authorisation be used instead of the login screen.
Yes, set the $WEB_AUTH parameter to "Y" in /config/config.php. Username is taken from the REMOTE_USER environment variable set by Apache.
5. What web browsers is WebCollab compatible with?
WebCollab is valid XHTML 1.0 and uses CSS1 cascading style sheets. Some Javascript is used, but this is not essential. This means WebCollab is compatible with most contemporary web browsers.
6. My ISP only gives me one database with my account. Can WebCollab share a database with another application, or applications?
Yes, the easiest way is to manually add a unique prefix to the all the table names SQL in /db directory. A suitable prefix might be 'webcollab_'. After that the tables can be created by running setup, or by doing a manual SQL creation (see the INSTALL file). Finally, the line in /config/config.php that reads 'define("PRE", "" )' needs to be altered accordingly. For the example above, this would become 'define("PRE", "webcollab_" )'.

PERFORMANCE TUNING

1. Can output buffering be used to speed up WebCollab?
WebCollab is normally very fast. Most bottlenecks are caused by database performance rather than PHP throughput.

The /includes/screen.php file contains 'commented out' code for compressed output buffering with ob_handler(). When this is enabled the output to the browser will be 'gzipped' before transmission, providing the browser is capable of accepting gzipped HTML - and most are. However, there is a downside to this form of output buffering: Compression does not start until all the page is rendered by the web server. This creates a noticeably high latency in page loading; for this reason the code has been 'commented out' in WebCollab.

The preferred method of output buffering is with zlib.output_compression set in php.ini. Refer to PHP Manual for more information. The downside of this option is that zlib.output_compression is not available on all versions or flavours of PHP.
2. Is caching worthwhile?
WebCollab uses a modular codebase with a high reuse factor. Compiler caches will work well with WebCollab. Ioncube PHP Accelerator has proven very compatible with WebCollab; Turck MMCache and Zend products should also work well.

UPLOADING FILES

1. Error message about directory not writable when uploading files with the file upload feature.
For Linux and *nix: Make sure the /files/filebase directory is writable by the web server. This means the directory should be either owned by the web server user (usually apache, www or www-data) or the directory must be world-writable.

Use 'chmod 777 filebase' from the files directory, and preferably move the directory outside the web server root - see item 3 below.
2. File upload gives message about server configuration not allowing uploads.
Check that the PHP configuration file, php.ini, is set to allow file uploads. Check that 'file_uploads = On', or file uploads cannot work.
3. Increasing the file upload limit for bigger files.
There are three configuration files that the control the upload file size:
  1. The $FILE_MAXSIZE parameter in /webcollab/config/config.php. This can be changed by the setup program, or by manual edit of the file.
    //max uploaded file size in bytes (2 Mb is the default)
$FILE_MAXSIZE = 2000000;
    The default file size limit is 2 Mb.
  2. There are settings in Apache which you may need to change. In particular this affects large file uploads. On Red Hat Linux this setting is very low by default, you can change the limit by adding or editing a lines in Apache's httpd.conf with the upload size in bytes (different operating systems may have these files in different locations):
    <Files  *.php>
   SetOutputFilter PHP
   SetInputFilter PHP
   LimitRequestBody 10485760
</Files>
    The size limit in this example is 10 Mb (10,485,760 bytes)
  3. PHP also has two more byte limits, which you can set in php.ini, and sometimes in a .htaccess file:
    php_value upload_max_filesize 20000000
php_value post_max_size 20000000
    The default size limit is 2 Mb.
4. File upload security.
If you use the default /files/filebase directory, it is possible for users to navigate to the directory with their browsers and view the files present. WebCollab has the /filebase directory protected by a index.html file and .htaccess file. Also, the filenames have a ID prefix added to them to prevent filename 'guessing' by attackers, but none of these measures are particularly foolproof.

Ideally, for good security move the file upload directory to outside the web server root directory. WebCollab can accommodate an upload directory in any location of the local file system - not just the web server root directory. Make sure the chosen directory is writable by the user that normally runs the web server.

EMAIL SETUP

1. How does email work in WebCollab?
Early versions of WebCollab used the mail() function call in PHP. In most cases it worked, but it proved troublesome with some SMTP servers.

WebCollab now uses the standard SMTP protocol over TCP/IP to 'talk' to a mail server. The mail server can be remote or local. Internally mail is handled by a purpose written SMTP mailer that is compliant to RFC 821 (RFC 2821), RFC 822, et al, for SMTP.

In /config/config.php:

$SMTP_HOST = DNS name or IP address of the SMTP server
2. My SMTP server needs me to use SMTP AUTH before accepting mail!
If SMTP AUTH is enabled in the config file, WebCollab will automatically login with 'plain', 'login' or 'CRAM-MD5' authorisation. The required auth format is automatically detected.

You need to set your login name and password in the /config/config.php file.

WebCollab complies to RFC 2195 (CRAM-MD5), RFC 2554 (SMTP AUTH) and RFC 2595 (auth plain).
3. Can WebCollab handle non US-ASCII characters (i.e. Languages other than US English)?
For languages with more than "US-ASCII" characters (e.g.: French, German, Spanish etc), WebCollab attempts to send emails in 8 bit format. This is accepted by almost all mail servers. Sendmail, for instance, has had 8 bit support since 1993.

If the upstream SMTP server does not advertise support for 8 bit mail, WebCollab reverts to 'quoted-printable' encoding. This follows the requirements of RFC 1652 (8BITMIME), RFC 1869 (Extended EHLO), RFC 2045 (quoted-printable), and RFC 2047 (8 bit extensions).
4. Common problems getting email to work.
5. What is the mailing list (mentioned in Admin Email), and how does it work?
The mailing list is set up in Admin Config, which can only be accessed by an admin.

Every email sent by WebCollab (except user details) is also sent to the mailing list. Users on the mailing list will then get a lot of mail, but they will be fully abreast of the site workings.

SECURITY

1. What are practical measures to increase site security?
WebCollab has been coded with strong security measures. In practical use WebCollab security has proven to be very robust.

Practical measures to enhance security include:

INTERNATIONALISATION

1. What character encoding does WebCollab use? Or, what characters can be used with WebCollab?
The character encoding is set by the language file in use. For instance, English, French & German all use ISO-8859-1 encoding (this is also known as Latin 1 encoding). WebCollab is fully internationalised and language files should be able to be set up with most international character encodings. Multi-byte character encodings schemes will probably need the (optional) multi-byte strings library installed in PHP, and the related mb_function overloading to be enabled in php.ini.

For better internationalisation capability, the Unicode version of WebCollab should be used. This natively supports over 650 languages. The database and PHP requirements, are however, much more stringent.

REMOTE DATABASE

1. Why can't remote databases be used with PostgreSQL?
Since version 6.3 (March 1998) PostgreSQL uses UNIX domain sockets by default. TCP port will NOT be opened by default. The TCP option can be enabled with the '-i' flag to postmaster and it's meaning is: "listen on TCP/ IP sockets as well as Unix domain sockets".

Usually the pg_hba.conf (PostgreSQL config file) also needs to be edited to allow TCP/IP connections.

Changing $DATABASE_HOST in config.php from "localhost" to anything else (including 127.0.0.1) without reconfiguring PostgreSQL will always prevent WebCollab from connecting to the database.

DATABASE TYPES

1. What are the database types in the config file?
postgresql=> PostgreSQL abstraction layer
mysql=> standard MySQL abstraction layer
mysql_innodb=> MySQL abstraction layer with innodb transaction support
2. PHP5 is bundled with SQLite. Why doesn't WebCollab support this too?
At present SQLite does not have sufficient date/time functions to work with the WebCollab code.

TRANSACTIONS

1. Are database transactions used?
The PostgreSQL abstraction layer always uses transactions because:
The mysql_innodb abstraction layer also uses transactions.

For MySQL version 4.0, and above, innodb database support is enabled by default. For these versions (and configured 3.23.xx versions) it is recommended that the database be created with the mysql_innodb database creation script, and the mysql_innodb abstraction layer is used.

For MySQL version 3.23.xx the database server must first be correctly configured to allow innodb databases to be used. See the on line MySQL manual for more details:
http://www.mysql.com/doc/en/InnoDB_in_MySQL_3.23.html

DATABASE BACKUP

1. Can the database be backed up?
Two UNIX based shell scripts are provided in /db for backing up WebCollab databases.

MySQL:

dump_mysql.sh
   Usage: dump_mysql.sh  <database user> <database name> <database password>

PostgreSQL:

dump_postgresql.sh
   Usage: dump_postgresql.sh  <database name>

Both dump into a plain text file. They can be automated with a cron job and emailed to a back up machine at regular intervals.

TRANSLATIONS

1. Can I translate WebCollab text messages to my language? And how do I do it?
The message translation files are in the /lang directory. Using English as an example, there are three main files:
  1. en_message.php - message strings used in the program.
  2. en_long_message.php - long text descriptions used in a few screens.
  3. en_email.php - text used in the automated emails.
Each file contains a single string per line, with an id on the left hand side. For example:

"planned" => "Planned (not active)"

Translate the right hand side to your language. Save the file (replacing 'en' with your language).

The 'help' files are similar, but are mostly written in HTML text. They are found in the /help directory.
2. How do I install the translation files that I've written?
Either:
Final step is obviously to alter the locale in the /config/config file.