Sie sind auf Seite 1von 49

04.

Administrator's Guide

Getting Started
In this chapter you will learn how to get activeCollab up and running on your own server. First, we will describe all the server
requirements that are necessary in order to run activeCollab nicely and smoothly. Then, we will lead you through the installation
process, one step at a time. Finally, we will give you some advice in order to help you make sure that your copy of activeCollab is totally
secure.
Let's get started!

System Requirements
activeCollab is a PHP-based application that must be downloaded and installed on a server in order to run (after purchasing a licence).
Currently, it is not available as a hosted service.
The minimum system requirements that your web server must meet in order to run activeCollab are:
Web server with PHP 5.3 or PHP 5.4 support (latest stable recommended) with mysql, PCRE, XML, ctype, tokenizer,
session, xml, dom, phar, zlib and json extension installed. activeCollab is known to work well on Apache and IIS. Other web servers
might also work, but we haven't tested these configurations.
One MySQL database.
activeCollab comes with no specific hardware requirements. You should use hardware that can serve the platform that you
picked (Windows, Linux, Mac OS etc) while running an application that uses between 50MB and 1GB of RAM (depending on
number of users, memory caching settings etc).
We recommend the following system configuration:
Apache 2 with support to run PHP scripts.
PHP 5.4 with mysql, PCRE, XML, ctype, tokenizer, session, xml, dom, json, gd, mbstring, iconv, phar, zlib and IMAP extensions.
MySQL 5 with InnoDB storage engine enabled.
Memory limit set to at least 64MB, but we highly recommend 128MB (it is configured in your php.ini file). Depending on your
reporting needs and the way that you configure thumbnail generation, more memory may be required in order to handle usage
peaks (when preparing big reports or resizing big images).
activeCollab does not work under eAccelerator or XCache. Please disable them before installing activeCollab and consider using
APC instead.
For reliable production use, we recommend hosting with guaranteed resources (VPS or dedicated) over shared
hosting.
Optional Extensions
The following PHP extensions are required for some optional features to work, but they are not required for the system itself to operate:
1. If you wish to use CAPTCHA protection with the Public Submit module, you will need to have the GD extension enabled with
FreeType support.
2. If you wish to use the Incoming Mail module, so that activeCollab can read emails, post responses as comments, or add new
messages as Discussions or Tickets, your system must have the IMAP PHP extension installed.
3. SVN extension is also recommended if you wish to browse your SVN repository by using activeCollab Source Module.
To access and use activeCollab, your users will need to have a modern web browser with JavaScript enabled. We test and
officially support:
Internet Explorer 9 and higher. System works in Internet Explorer 8 as well, but some features may be slower or not as polished as
the latest version of Microsoft's browser. Please, use the latest stable version of Internet Explorer for optimal performance and
user experience.
Latest stable version of Google Chrome.

Latest stable version of Mozilla Firefox.


Latest stable version of Apple Safari.
activeCollab is optimized for 1280x800px or a higher screen resolution, but it also works well in modern mobile browsers, such is
Mobile Safari, on iPhone and iPad.

Supported Web Browsers


*Logos and product names used on this page are trademarks, or registered trademarks of their rightful owners.

1. Test if your server meets activeCollab System Requirements


To see if your system meets the system requirements, you can use the probe.php script, designed specifically for this
purpose.
Here is how:
1. Download the probe.php.zip file here;
2. Unpack and upload the probe.php file to your server;
3. Run it through your web browser;
4. Optionally, you can open the probe.php file in your favorite text editor and set the database connection parameters, in
the Database Settings section, at the beginning of the file. Once these parameters have been set, save the file on the
server and run it again.
It will run a check of your platform and additionally try to connect to the database and see if it meets the system
requirements.

In action: probe.php

2. How to Turn Off eAccelerator or XCache?


activeCollab does not work well if your server has eAccelerator or XCache configured. Our installation tool will warn you
about this problem and it will not let you proceed, unless you turn off these tools.
To turn off eAccelerator, you will need to make the following changes in your PHP configuration:
eaccelerator.enable 0
eaccelerator.optimizer 0
XCache is similar. To turn off XCache, please make the following changes to your PHP configuration:
xcache.cacher Off
xcache.size 0
xcache.stat Off
Where exactly these changes need to be made depends on your server's configuration. In some cases, where you have access
to global PHP settings, you can update the main PHP configuration file (called php.ini in most cases). In other cases, where
your host allows changes per folder (via separate php.ini or .htaccess files), make sure that these changes apply to the
/public folder of your activeCollab, since all requests are routed through that folder.
For example, if your host lets you override the PHP settings with .htaccess files, you would need to create the .htaccess
file in the /public folder of your activeCollab, and put the following content in it:
php_flag eaccelerator.enable 0

php_flag eaccelerator.optimizer 0
Please consult your hosting provider for specific information.
Use APC for Opcode Caching
We recommend that you use APC for opcode and memory caching. When enabled, your PHP will cache the processed PHP
files and will not waste time on file processing on each request (which results in significant performance gain). Also,
activeCollab will automatically start using it as the primary caching mechanism, instead of a file based cache, which will also
speed things up.
APC is highly recommended if you want good system performance.

Installation
Important Note
Please make sure that whenever you install or upgrade activeCollab, when uploading files using FTP, to always use Binary transfer
mode. Using any other mode can cause the files to become corrupted and render them invalid
The activeCollab installation can be completed in six simple steps:
1. Ensure that your server meets activeCollab's System Requirements. If your server does not, or is not properly configured, you will
not be able to run the installation tool;
2. Create a MySQL database where activeCollab will store the data. If you already have a database set up, this step is optional;
3. Download the activeCollab installation package from your profile page on the activeCollab website;
4. Upload the contents of the /for-upload folder onto your server;
5. Run the installer tool;
6. Log in for the first time and verify that the system is working properly.
Read on to learn more about each of these steps.

1. Meeting System Requirements


Before you start the installation, please make sure that your server meets the activeCollab System Requirements.
activeCollab works well on most platforms which have a web server with PHP support and MySQL database.
To see if your system meets the system requirements, use the probe.php script, designed specifically for this purpose.
Here's how:
1. Download the probe.php.zip file here;
2. Unpack and upload the probe.php file to your server;
3. Run it through your web browser;
4. Open the probe.php file in your favorite text editor and set the database connection parameters in the Database
Settings section at the beginning of the file. Once these parameters are set, save the file on the server and run it again. It
will run a check of your platform and additionally try to connect to the database and see if it meets the system
requirements.

In action: probe.php

2. Creating a Database
activeCollab installer will not created a database for you, so please make sure that you have a database available for your
activeCollab installation before continuing with the install process. If you don't have a database, you can create it by using
your favorite MySQL administration tool (phpMyAdmin, for instance) or contact your system administrator to create a
database for you:

Creating a new database using phpMyAdmin


After creating the database, write down the following details:
The database host name (usually "localhost") as well as the database username and password;
The name of the database that you just created.
activeCollab installer will ask for the same details later and you won't be able to perform the installation without them.

3. Downloading activeCollab
Before you can install activeCollab, you'll need to download activeCollab installation package from your profile page on the
www.activeCollab.com website. To be able to see and download installation package, please login with the same account you
used to purchase the license:

4. Uploading Files to the Server


Once you have downloaded and unpacked the installation package using your favorite ZIP utility, you will see the following
files and folders:
/for-upload - activeCollab files that you need to upload to your server;
license.txt - the activeCollab End User license agreement;
readme.txt - basic information about activeCollab and links to additional resources;
release-notes.txt - information about both current and previous releases.
You do not need to upload all these files to your server. Instead, you should upload only the contents of the /for-upload
folder:

5. Running Installer Tool


Once you have uploaded files from the /for-upload folder to your server, you can run the activeCollab installer. The installer
tool can be run with any web browser. In fact, if you try to open any of the activeCollab pages at this point, the system will
present you with the installer tool instead.

Before installation process beings, activeCollab installer will first validate your environment:

During installation process, activeCollab installer will ask you to provide:


1. Database connection parameters that you've prepared in Step 2;
2. Email address and password of the administrator account (it's usually your own account);
3. Your acceptance of the activeCollab License Agreement.
If the installation is run properly, the system will display several OK messages and provide you with a link to the login
screen, where you can use the administrator email address and password (which you defined earlier) to login:
Image location not provided

6. Verifying that the System is Working Properly


After you have run the installation tool, you can visit your new activeCollab setup. If everything has gone well, the system
will display a simple login screen where you can login using the administrator username and password, which you provided
during the installation:

If you don't see the login screen or see an error message or blank page instead, please consult the Troubleshooting guide or
contact our support team.

7. Importing the data form the Hosted Demo


If you were evaluating activeCollab before you have decided to purchase the license, you can have exactly the same setup as
you created in the Hosted Demo in your installed activeCollab. All you need to do is to import your demo database into your
hosted activeCollab.
Before making the actual import you have to get the demo data. They are available on your www.activeCollab.com profile
page under the Export demo data link.

Now that you have the exported archive here's what you need to do to import it into your activeCollab:
1. Upload the contents of all directories from the archive file to respective directories at your activeCollab setup (overwrite
the existing files);
2. Delete all tables from activeCollab database and import the data from .sql file located in the archive;
3. Delete all files having .php extension from /cache directory;
4. Delete all files having .php extension from /compile directory;
5. Edit /config/config.php and set table prefix to your instance name. For example, if your demo instance was
http://mydemo.tryactivecollab.com, then you should set the table prefix to "mydemo_".
After completing all of these steps, you should be able to see all your data from the Hosted Demo in your installed
activeCollab.
If you have any difficulties, feel free to contact us, and we'll help you set your activeCollab.

Securing Your System


activeCollab application is secure right out of the box, but there are still a couple of things that you can do to make your own setup as
secure as possible:

1. Install the System Behind the Document Root


Installing the system above the site root ensures that only files from the /public folder are publicly available, while all
other files are not accessible on the web. Even though the system encodes file names and comes with .htaccess rotection by
default for folders with sensitive data (/upload, /thumbnails and other), the very best approach is to have them installed
above the site root.
Instructions on how to set up the activeCollab in this way are available here: /public Folder as Document Root.

2. Use SSL Encryption


activeCollab is protocol agnostic, so if your server supports SSL and has proper certificates installed, it will work on
HTTPS as well as on HTTP. All you need to do is to run the Installer on the proper protocol and it will use the HTTPS
URL automatically.
If you have activeCollab already installed on HTTP, and then decide to add a certificate later so it can work over HTTPS,
you can change the protocol in the config/config.php file:
define('ROOT_URL', 'http://example.com/public')
All you need to do is to use https:// instead of http:// protocol in ROOT_URL value:
define('ROOT_URL', 'https://example.com/public')
After you have updated the ROOT_URL don't forget to delete files with "cch_" in the beginning in your /cache folder and
files with "%%" from the /compile folder.

Configuration
In this section, you'll learn how to configure activeCollab the way you want it and get the best out of all the different features available to
you.

Scheduled Tasks
Some activeCollab modules need to be run periodically in order to perform their tasks and functionality. For instance, the invoicing
module should be run daily if you wish to automatically create and send invoices configured using "Recurring Profiles" feature.
All of these events are executed by periodically making a web request on specific activeCollab URL/URLs or executing specific PHP files
through command lines (check this article for details). There are three time periods which activeCollab supports:
1. frequently - Should be executed frequently. We recommend every 3 minutes, but you can use any value between 1 - 5 minutes.
2. hourly - Should be executed every hour.
3. daily - Should be executed every day.
Command examples with exact paths and URL/URLs that need to be triggered are available on the Administration > Scheduled
Tasks page:

Note
activeCollab has two different ways for generating URLs. Because of that, URLs in your system may look a bit different to the URLs
displayed in a screenshot or used in other examples.
Scheduled Tasks page in Administration is also used to check when was the last time these events were triggered, so it's useful for
troubleshooting actions that are executed on events triggered by scheduled tasks.

1. Operations Dependent on Scheduled Tasks


It's important that you have scheduled tasks configured and firing for activeCollab to work properly. Here's a list of various
operations that are executed by scheduled tasks.
Frequently task is used for:

1. Sending outgoing email notifications for the mailing queue


2. Importing email messages from defined mailboxes
3. Sending reminders that are set to be sent at a given date and time
4. Checking source repositories for new commits
Hourly task is used for:
1. Cleaning up environment cache
2. Checking source repositories for new commits
Daily task is used for:
1. To send recurring invoices for a given day
2. Checking source repositories for new commits
3. Cleaning up various caches and commit daily summaries
Note
This list applies to activeCollab 3.1. Custom modules may also require one of the three events triggered by Scheduled Tasks
to work properly.

2. Direct Access Protection


Scheduled Task URLs can be protected from direct visits by adding the first five letters of your license key as a code
parameter:
http://example.com/collab/frequently?code=QGNig
Protection is automatically turned on for all new installations since activeCollab 2.1. If you upgraded from a
version older than 2.1 to the latest version, please add the following code to your config/config.php file in order to enable it:
define("PROTECT_SCHEDULED_TASKS", true);
Note that you'll need to update your cron configuration once you have done so because this changes the URLs that need to be
pinged.

3. Methods of Triggering Tasks


Scheduled tasks in activeCollab can be triggered in two ways:
1. by triggering a task URL with a utility such as curl, wget, etc.
2. by executing a specific PHP file using a PHP command line utility
Both of these approaches have advantages and disadvantages. For example, using PHP to trigger files skips the web server
and the overhead that it adds, but you will need to have the PHP command line utility configured on your server. On the
other hand, triggering a URL always works when activeCollab is properly configured, but it's a little slower because the web
server is added to the mix.
Examples:
/usr/bin/curl -s -L "http://url/of/hourly/task" > /dev/null
/usr/bin/php "/path/to/activecollab/tasks/hourly.php" > /dev/null
The exact commands you need to execute are listed on the Administration > Scheduled Tasks page of your activeCollab
installation.

4. Trigger Tasks with cron (Linux, BSD etc)

In order for events to work you'll need to set-up some kind of scheduling software to execute task scripts or ping specific
activeCollab URLs at specific times.
For example, on UNIX you can use cron and PHP or curl to achieve this. Open crontab for editing by executing:
crontab -e
in your command line. Then insert the following text into the field:
*/3

php "/path/to/activecollab/tasks/frequently.php" > /dev/null

php "/path/to/activecollab/tasks/hourly.php" > /dev/null

12

php "/path/to/activecollab/tasks/daily.php" > /dev/null

and save it. This will tell PHP to execute task files:
1. Every 3 minutes for frequently tasks.
2. On an hourly script on 0 minute of every hour.
3. On a daily script every day at noon.
If the PHP command line interface is not available on your server, you can use curl to request specific URLs to trigger events.
activeCollab behaves the same way as task files, but instead of using a PHP command line utility, tasks are invoked by the
web server. Here are the commands that you'll need to set in the crontab file:
*/3

/usr/bin/curl -s -L "http://url/of/frequently/task" > /dev/null

/usr/bin/curl -s -L "http://url/of/hourly/task" > /dev/null

12

/usr/bin/curl -s -L "http://url/of/daily/task" > /dev/null

5. Trigger Tasks with Scheduled Tasks (Windows)


On Windows you can also use Scheduled Tasks to trigger scheduled tasks in activeCollab. To set-up Scheduled Tasks on
Windows XP, Vista and Windows 7 (as well as Windows 2003 Server or later) you can use schtasks.exe. To do so, open the
command line and type in the following commands:
schtasks /create /ru "System" /sc minute /mo 3 /tn "activeCollab frequently job" /tr "C:\php\php.exe
C:\activecollab\tasks\frequently.php -f"
schtasks /create /ru "System" /sc hourly /st 12:00:00 /tn "activeCollab hourly job" /tr "C:\php\php.exe
C:\activecollab\tasks\hourly.php -f"
schtasks /create /ru "System" /sc daily /st 12:00:00 /tn "activeCollab daily job" /tr "C:\php\php.exe
C:\activecollab\tasks\daily.php -f"
Important note
Please pay attention to following details:
1. Use the real path to your php.exe file.
2. Use exact paths to frequently.php, daily.php and hourly.php files, as found on the Administration > Scheduled Tasks
page.
3. If you have white spaces in you paths to php.exe or activecollab folder you need to add \" to escape it. For example,
such cases:
schtasks /create /ru "System" /sc minute /mo 3 /tn "activeCollab frequently job" /tr "C:\Program Files
(x86)\php\php.exe C:\activecollab\tasks\frequently.php -f"
should be avoided like this:

schtasks /create /ru "System" /sc minute /mo 3 /tn "activeCollab frequently job" /tr "\"C:\Program Files
(x86)\php\php.exe\" C:\activecollab\tasks\frequently.php -f

6. Trigger Tasks with launchd (Mac OS X)


On Mac OS 10.4 Tiger or later, Apple recommends that you use launchd instead of cron, xinetd, mach_init, and init. Tasks
are defined as XML files that tell launchd what to do and when.
To define the three scheduled tasks that activeCollab requires, please create the following files in the /Library/LaunchAgents
folder and make sure that you set the correct task URLs (you can find them on the Administration > Scheduled Tasks page of
your activeCollab setup):
1. com.a51.activeCollabFrequently.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.a51.activeCollabFrequently</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/curl</string>
<string>-s</string>
<string>-L</string>
<string>https://my.activecollab.info/frequently?code=12345</string>
</array>
<key>StandardOutPath</key>
<string>/dev/null</string>
<key>StandardErrorPath</key>
<string>/tmp/ac_schedule_err.log</string>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>180</integer>
</dict>
</plist>
2. com.a51.activeCollabHourly.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.a51.activeCollabHourly</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/curl</string>
<string>-s</string>
<string>-L</string>
<string>https://my.activecollab.info/hourly?code=12345</string>
</array>
<key>StandardOutPath</key>
<string>/dev/null</string>

<key>StandardErrorPath</key>
<string>/tmp/ac_schedule_err.log</string>
<key>StartCalendarInterval</key>
<dict>
<key>Minute</key>
<integer>0</integer>
</dict>
</dict>
</plist>
3. com.a51.activeCollabDaily.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.a51.activeCollabDaily</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/curl</string>
<string>-s</string>
<string>-L</string>
<string>https://my.activecollab.info/daily?code=12345</string>
</array>
<key>StandardOutPath</key>
<string>/dev/null</string>
<key>StandardErrorPath</key>
<string>/tmp/ac_schedule_err.log</string>
<key>StartCalendarInterval</key>
<dict>
<key>Hour</key>
<integer>12</integer>
<key>Minute</key>
<integer>0</integer>
</dict>
</dict>
</plist>
These settings will define following tasks:
1. A frequently task that fires every 3 minutes;
2. An hourly task that fires at first minute of every hour;
3. A daily task that fires every day at noon (the server's time, not activeCollab's).
To see if everything is working properly, periodically check the Administration > Scheduled Tasks page to check the last time
tasks were executed successfully.

Outgoing Mail Setup


Outgoing Mail Settings page enables you to configure how activeCollab will send emails. To access this page, click the Email icon from
the Administration and go to the Change Settings page in the Outgoing Mail area.

activeCollab can work with emails in the way you choose. Select one of the following options for connection:
Disabled - system will not send any emails or notifications to users.
Silent - Notification and email system is working, but does not send any messages. This mode is great for testing, because you will
not disturbe anyone, but will be able to see the log.
Use Native Mailer - In this case, activeCollab will use the email server configured in your php.ini file. If the PHP is properly
configured, the system will send messages using mail() function.
Use SMTP Server - activeCollab will connect to an external SMTP server to send messages.
After setting up the way you wish your activeCollab to communicate, you can choose how email should be send:
Instantly - the system will send emails in the same requests in which they were prepared.
In the Background - the system will not slow down the request that prepared the notification, instead it will send the message as
soon as possible.
If preferred, you can allow users in your activeCollab to select the way they want to get their email messages themselves.

Finally, you should configure email address of the sender. From: email and From: name will be displayed on every email
notification your activeCollab sends. We suggest you to use a unique email address created only for this purpose.
Recommendation
We recommend you to to use the same email address in the Outgoing Mail setup and for Incoming Mail setup, to make sure all your
notifications are able to have reply's that will be imported in activeCollab. In this way replays will be placed in your activeCollab
automatically.

1. Reply to Comment Tool


Email notifications sent from activeCollab support replies that will be imported in to the system and placed as a new
comment on the object that triggers that notification originally.
To make sure all of your replies are working properly, we have created a tool inside activeCollab that will take care of it. It's
Reply to Comment tool, and you will find it in the Administration.

This tool is straight forward and it will help you spot and resolve the email conflict (if there is any) in no time.

Incoming Mail Setup


Email communication is a common business practice nowadays, and therefore it's an integral part of activeCollab.
Your activeCollab can check any number of POP3 or IMAP mailboxes and read emails from there. Messages that are found in these
mailboxes are then imported into activeCollab in a way you define and sorted into the correct part of the system. This
feature enables you not only to collaborate with your clients by using activeCollab only, but also to provide customer support, manage
your sales, track bugs in your software, have feature requests submitted, share files, etc.
Dependencies
For incoming mail to work properly in your activeCollab, the following conditions needs to be met:
1. IMAP extension needs to be installed in your PHP setup. If you plan to connect to POP3 and IMAP servers via SSL, make sure that
you have IMAP extension compiled with SSL support.
2. If you are checking mailboxes over a secure connection, PHP will also need to be compiled with SSL support.
3. Since the mailboxes that we are going to use will need to be checked frequently, you will need to configure activeCollab's Scheduled
Tasks.
We also highly recommend to create a new mailbox that will be used only for activeCollab. Please note that all emails from the
mailbox will be deleted right after activeCollab makes the import, so the best practice is to use a separate mailbox for this purpose,
instead of your business or private email.

1. Setting up a New Mailbox


To set a new mailbox that your activecollab will use go to the Administration > Email page and click the Manage
Mailboxes button.

A page will appear where you should click the New Mailbox button in the top right corner. Now you can configure your
mailbox. Information required here are usually provided by your hosting company. If not, feel free to contact them and ask
for the info you need.

Required fields in the new mailbox form are:


Account name and Email address - this email address will be checked frequently for new messages that will be
imported into activeCollab.
Server info such as a server type and adress, port (that must be opened on your server!), username and password, as
well as the security type you're using for this email account, and mailbox name; everything needs to be filled out
carefully to match the info you got from your hosting provider.
After submitting all the info, please check if your activeCollab can connect to a defined mailbox. Just click Test Connection
button and system will do let you know on the result.
You can create any number of mailboxes in this way.

2. Configuring Incoming Mail Filters


After creating a mailbox, you can define a set of rules that activeCollab will apply when receiving an email message from that
mailbox. In this way you can teach your activeCollab to manage incoming mails exactly in a way you wish.
For example, some of emails can be imported as a new task within a specific project with defined assignee, others can start a
discussion, or create a new file inside your activeCollab, or some of the messages you just want to trash.

To start creating filters you need click Manage Filters button in the Administration > Email area. In the top right
corner of the following page you will see New Filter button. Now set the following:
Filter Name - should be unique and straight forward to help you make the difference between multiple filters that you
can have.
Apply This Filter To option - offers to select all mailboxes or just one that will be used for this purpose. If not defined
filter will be applied to all mailboxes (as default setup)
Subject - enable it if you want to have emails with certain word in a subject treated differently. This option can come
in handy if, for example, you want to trash all emails with "Auto-responder" in their subject.
Body - use this criteria for the emails that has a specific word, or phrase included in their body text.
Priority - useful for the messages that should be emphasized as important.
Has Attachments - when enabled checks if email message has attached files or not.
Sender Email - use it if you wish to treat emails from specific group of uses in a a unique way.
To Email - when enabled can recognize the recipient's email address.
After we have set all the criteria needed we can define what exactly will be done with the email messages which fullfils
conditions set above. This will be determined in the Action box. Here we can choose to:
1. Move the email to Trash - incoming message will be trashed immediately and removed from your server.
2. Ignore - system will not register the email message.
3. Add New Task - email will be turned into a Task within selected project. You can even set Category, Label and
Assignee for this specific Task, as well as set the Milestone for it, enable unregistered users to submit such tasks, define
who should be listed as task creator. On top of that, you can also send an email notification about the task and create a
public page where non-registered users will be able to access it.

4. Add New Discussion - process is the same as described for creating a new task.
5. Add New File - same process as described when creating a new task.
Important Note
Please be aware that only one object can be created when applying a filter. This means that you can't have a new Task,
Discussion and File all created by applying one filter to an email message. Such an email can be used to create only one of
the project items.

3. Managing Incoming Mail Filters


You can create as many Incoming Mail Filters as you wish.
Be careful!
If you wish to use multiple incoming mail filters make sure you sort them by importance. activeCollab will check them one
by one, in order they are sorted. If the email matches the first filter, message will be imported according to the rules
defined in that filter. If not, activeCollab will continue to "search" the filter where that email message will fit.
To organize your filters use drag and drop functionality.

You will notice the magnifying glass icon in the filter tool bar. By clicking it, you will be able to see all important details
about that filter.
If you wish to make some editing on the filter just click the pencil icon and make the changes you wish.
Each of the filters created can be deleted at any time.

4. Resolving Conflicts
Occasionally, when incoming mail filters can't be apply to the email message found in the defined mailbox properly, a
conflict can occur.
You will know that a conflict has happened by: - receiving an email about a conflict in your activeCollab. Please note that
only Admin users will receive such emails. - You will see a number in the Control Tower bar.

To examine the conflict and resolve it go to Administration > Email and choose the Incoming Mail Conflicts tab. You
will see the list of messages describing what the conflict was about. To see more details you should click the magnifying glass
icon and a message with the full description will appear. This is aslo a place where you can resolve the conflict.

Some of the most common conflict scenarios are:


User don't have the permission to create an object
When creating incoming mail filter there is an option to allow only person who is registered user with proper
permission to submit a Task, Discussion or a File by using email. If you have included this option into the filter, only
registered users with Access and Create and Access, Create and Manage project permissions enabled will be allow to
create a new object in this way.
All emails send from non registered users or people who don't have sufficient project permission will cause a conflict in your
activeCollab. You can choose whether you wish to resolve this conflict and set the filter in other way to allow this type of
action, or to remove that email from the system.

Project don't exist


Remember to edit your Incoming Mail filters after removing a project from your activeCollab.
In case you have set the filter to create a new task (discussion or file) on a project that you have moved to trash in your
activeCollab, a conflict will occur. The system will not be aware of the location where the project item should be placed. You
can resolve the conflict either by choosing another project to be set as paret to new item, or by removing the email message.
Email is not matching to any of the filters
If the email message your activeCollab receives don't match any of filters created in your system, email will be ignored and

will cause a conflict.


To resolve it, simply adjust some of the filters to this specific email or create a new one that will handel such cases. You can
alway remove that email from your activeCollab.

Control Tower

Control Tower is set of administrator tools that are designed to alert administrator about any mail conflicts, mail in queue, if
scheduled tasks is set up correctly and if you have an incoming mailbox set up to be able to receive replies to email notifications. Control
Tower is available for administrators only and can be accessed by clicking the button at the bottom right hand corner of the interface.
You can also use it to Empty the Cache, Clear Compiled Templates, Rebuild Assets (Images, Fonts, Flash files etc) and Rebuild
Localization Dictionaries when needed.

1. Scheduled Tasks - When Scheduled Tasks is properly configured, light will show as green. Please note: If the frequently
command is triggering less frequently than every 10 mins, the hourly command triggering less frequently than every hour and the
daily command triggering less frequently than every 24 hours, the Scheduled Tasks indicator will show as red.
2. Reply to Comment - This light will show green when an all necessary requirements have been met to allow users to reply to
email notifications, and have those responses logged as comments on the relevant object (tasks, discussions, files etc).
3. Mailing Queue - When light is green there is no mail in the mailing queue.
4. Mail Conflicts - When light is green, there are no mail conflicts.
Setting which indicators you wish to show in the control tower can be done in admin panel.

Languages
Localization Support in activeCollab enables you to have multiple languages available and used at the same time. It practically means
that each user in your activeCollab can use the application interface in their native language.
The Languages tool, in the Admin area, allows you to create and import any number of languages that you need. The only language
that is available by default is English.

There are two ways to create a new language in activeCollab:


Create a new translation on your own - click on the New Language button, name the language and choose the local code. A
dictionary will appear where you can translate each phrase used in activeCollab.

Import the XML language file - to be able to do that, you will need to export the translation file made with activeCollab. A few
of our community members have decided to share the translations that they made, so you can choose to use some of them. You will
find this on the Translations page of our website.
When having a few languages available, you can select which one will be the default language. Use the Set Default Language button,
in order to do that. A form will appear where you can mark the language that will used as default.

If you are working with people from different countries, you can make activeCollab more convenient for them by giving them an
opportunity to use activeCollab in their native language. To set this up, go to the user's profile page and use the Change Setting option
from the Options menu. Here, you will see the Localization setup and the Language drop down menu. Simply select the language
that you wish and click on the Save changes button.

Roles and Permissions


Roles and Permissions enable you to define what people can and cannot do in your activeCollab installation. There are two types of roles
in activeCollab: system roles and project roles.

1. System Roles
System Roles lets you configure what a user can do in the system - eg. access administration controls, manage people or
projects, create and access assignment filters, etc. Each user can only have one System Role that controls what they can do
on a system level. This role is set when the user account is created and can be changed at any time on the Profile page of the
given user in the Company and Role dialog. System roles can be found and fine-tuned in Roles and Permissions tool
under General section in the administration panel.
You can give your users a default system role or edit one to suit your needs or create a completely new system role.

To edit an existing role simply click on the Edit button that looks like a pencil on Administration > Roles and
Permissions page as shown above.
You can also configure a default homescreen for a role so every user with that role will have the same, pre-configured home
screen. Please see Configuring your Homescreen for more information on this topic.
Every system role consists of the following permission options that you can grant or forbid:

You can see what each of these permission do by holding your mouse cursor over the permission in your activeCollab.
Permission

Description

system_access

This permission defines whether user has permission to access the system. System
Set this to No if you don't want to delete specific user accounts but you want
to restrict them access to the system.

Module

administration_access

Set this permission to Yes if you want to give administration permissions to System
users with selected role. This permission overrides every other permissions
and additionally gives access to administration panel to users who have it.

use_api

Set this permission to Yes if you want to let users use API. API is used to let System
external applications work with application data (calendar applications,
RSS readers, specialized tools like timer applications etc).

use_feeds

Set this permission to Yes if you want to let users use feeds. Feeds are used System
to let external applications work with application data (calendar
applications, RSS readers etc).

see_private_objects

Set to Yes for roles that you want to be able to see objects marked as private. System
Usually this is set to Yes only for the members of your own company and to
No for the client roles to hide sensitive, internal discussions and other
confidential information.

manage_trashed_data

People with this permissions can list objects that are moved to trash. This

System

permission also lets people to restore object from trash, or to permanently


remove them from the system.
project_management

Project managers are people who can do anything with all projects. They

System

can see and access any project and they have all the permissions in them.
Project managers can create projects even if 'add_project' permission is set
to No!
create_new_projects

Set whether user can create new projects or not. When creating a project

System

members of client companies will see ONLY people and companies they
have previously worked with. They will not see everyone! Administrators
and project managers can create new project no matter which value this
permission has!
see_project_budgets

Set whether user can see budget details for projects. Budget details are great System
for managers and (sometimes) clients, but you usually don't want to have
this information available to all employees and sub-contractors.

people_management

People managers have all permissions regarding account management in

System

People section. They can create new and manage all existing users and
companies without any restriction.
manage_company_details

Set to Yes if you want to allow client company employee to manage

System

company details. This user will be able to change its own company
information, add new people to that company, and receive and access
Invoices issued to that company.
see_contact_details

People with this permission set to Yes in their system role can see contact

System

details of other users in the system.


configure_own_home_screen Allow users with this role to configure their own home screen. When this

System

permission is set to No, system will not allow users to configure their own
home screen and it will use home screen configured for this role (or global
home screen if role does not have home screen configured).
manage_assignment_filters

Set to Yes for roles you want to be able to create new and manage existing

System

assignment filters. If set to No users will be able just to use existing filters,
but not to create new or change setting of existing ones.
access_global_documents

Set to Yes to let users access Global Documents section, and view files and

Documents

documents that are available in that section.


manage_finances

his permissions enables users to view existing and create new invoices,

Invoice

manage payments, as well as to run all invoicing and payment related


reports.
manage_quotes

This permissions enables users to manage quotes within Invoicing module. Invoice

use_status_update

Set to Yes to let people use a simple communication tool that is easily

Status

accessible from all system pages.

Update

2. Project Roles
Project roles enables you to give or restrict access to specific sections and features inside a project. One great thing about
project permissions is that they work on a per-project basis. For example, you may want a user to be able to start new
Discussions in one project, but you dont want to give them access to Discussions in another project.
Unlike System roles, each user can have as many different project roles as projects they are working on (though only one
project role per project). The project role is set when the user is added to the project, via the People tab. Predefined project
roles can be found and managed on Project Roles page under Projects section in activeCollab's administration panel.
Project roles added here will be available when adding users to the projects.

Deleting a Project Role


Only roles that are not already in use by people in projects can be deleted!
These are the options that are in every project role:

Custom Fields
If you need to have some additional info in activeCollab on your Projects or Tasks, you can use Custom Fields feature. By using it you
can add up to 3 new custom fields on your Projects and Tasks.
You can also use criteria defined in custom field to list your Projects and Tasks by using this option from the Group By drop
down menu.

Here's how you can enable custom fields:

1. To the Project
If you wish to use Custom Fields on a New Project form, you need to enable it first. To do that go to Administration >
Project Settings, enable the fields you wish to use and name them.

After doing so, you will see additional fields on the New Project form. It will look something like this:

You can use Custom Fields labels as a criteria for project grouping, as you can see here:

2. To the Task
To enable Custom Fields for Tasks, visit Administration pannel again. This time use the Tasks Settings tool and click
the Change Settings button. A form will appear where you can enable up to three custom field and label them.
These fie;ds will appear on the New Task form:

and you will be able to use them for Task grouping.

Upgrade Instructions
In this section you can learn how to upgrade your copy of activeCollab to the latest release.

Upgrading to the Latest Stable Release


Before continuing with upgrade to the latest stable release, please check the version that you are currently running. Version number is
available in System Information block on Administration page of your activeCollab installation:

Based on the version that you currently have installed, please pick one of the following instruction sets:
1. If you have activeCollab 3.3.x or later click here.
2. If you have activeCollab 3.1.x or later click here.
3. If you have activeCollab 2.3.x click here.
4. If you have activeCollab 3.0.x click here.
Important Note
Please make sure that whenever you install or upgrade activeCollab, when uploading files using FTP, to always use Binary transfer
mode. Using any other mode can cause the files to become corrupted and render them invalid

Automatic Upgrade (Available for activeCollab 3.3, 4.0, 4.1)


In activeCollab 3.3, we introduce an auto-upgrade feature that will automatically download all new versions of activeCollab, that will
update your system by itself. Start by clicking on the Update button in the Administration page:

This will open the auto-upgrade dialog. Provide your password, and let the system do the rest:

Important Note
Please note that the upgrade process via activeCollab Manager is not possible with version 3.3.x. Feel free to use the activeCollab
Manager to conduct an upgrade, or maintain any of the earlier versions of activeCollab.
If you have any questions or concerns, feel free to get in touch with our support team.

Manual Upgrade (Available for activeCollab 3.1, 3.2, 3.3, 4.0, 4.1)
In activeCollab 3, the manual upgrade process is simplified. To start, download the latest activeCollab 3 build from your
activeCollab.com profile:

Unpack the archive and open /for-upload/activecollab folder. In that folder you'll find code for latest version of the system. Upload
latest stable version to /activecollab folder of your activeCollab setup on your server:

After you have latest version of activeCollab files uploaded, visit /public/upgrade/index.php part of your activeCollab with your web
browser, log in with your administrator credentials and let the system upgrade your database:

To confirm that you have successfully upgraded activeCollab, open config/versions.php and make sure that upgrade script has written
the valid version number in it.

Upgrading Legacy Releases


Use articles in this section if you are upgrading from a release older than activeCollab 3.1. If you have activeCollab 3.1 or newer,
please check instructions provided in this section.

Manual Upgrade (Instruction for activeCollab 2.3.x Users)


System Requirements
Before continuing, make sure that your server meets activeCollab 3 system requirements because activeCollab 3 has a significantly
higher requirements that activeCollab 2!
Latest activeCollab 3 relase is available to all customers with valid support and upgrade, and they can download it for their profile
pages:

Important Note: Avoiding Problems Caused by Limitations of PHP Environment


There are a couple of important things that you should check before starting the upgrade process:
check what is the memory_limit set in your PHP configuration on your server. It should be at least 64MB, but we highly
recommend 128MB if possible. If it is less then 64MB activeCollab upgrade script will not be executed.
also, look into the max_execution_time value in your PHP configuration. It should be set temporarily to a few minutes. After the
upgrade process is finished you can set it to its original value (30 seconds by default, or 60 seconds if you run scheduled tasks via
curl and have a lot of POP3 and IMAP mailboxes and/or repositories to check).
These settings will help to make a successful upgrade with minimal downtime.
Now, lets start with a bit of clean up:
1. Backup custom images from /public/avatars, /public/logos and /public/projects_icons subfolders,
2. Remove index.php and api.php,
3. Delete /activecollab folder,
4. Delete /public folder,
5. Delete /tasks folder,
6. Delete /config/defaults.php file.
Next, upload new files from activeCollab 3 installation package:
1. Upload /activecollab folder,
2. Upload /public folder,
3. Upload custom images from your backup back to /public/avatars, /public/logos and /public/projects_icons subfolders,
4. Upload /tasks folder,
5. Upload index.php and api.php,
6. Upload /config/defaults.php and /config/version.php file,
7. Create empty /custom/layouts and /custom/modules folders.

When new activeCollab 3 files are uploaded, make sure that following folders are set as writable:
1. /public/assets,
2. /public/avatars,
3. /public/logos,
4. /public/notebook_covers,
5. /public/projects_icons.
There's just one more step to do: fix configuration file. To do that, you'll need to open /config/config.php file and add following lines to
it, in block where other options are defined:
define('USE_UNPACKED_FILES', true);
and than replace:
require_once 'defaults.php';
require_once 'license.php';
with:
require_once dirname(__FILE__) . '/version.php';
require_once dirname(__FILE__) . '/license.php';
require_once dirname(__FILE__) . '/defaults.php';
After these changes, your configuration file will look something like this:
<?php
define('ROOT', '');
define('PUBLIC_FOLDER_NAME', 'public');
define('DB_HOST', '');
define('DB_USER', '');
define('DB_PASS', '');
define('DB_NAME', '');
define('DB_CAN_TRANSACT', true);
define('TABLE_PREFIX', 'acx_');
define('ROOT_URL', '');
define('PATH_INFO_THROUGH_QUERY_STRING', true);
define('FORCE_QUERY_STRING', true);
define('LOCALIZATION_ENABLED', false);
define('ADMIN_EMAIL', '');
define('DEBUG', 1);
define('API_STATUS', 1);
define('PROTECT_SCHEDULED_TASKS', true);
define('DB_CHARSET', 'utf8');
// Lines bellow are new to activeCollab 3
define('USE_UNPACKED_FILES', true);
require_once dirname(__FILE__) . '/version.php';
require_once dirname(__FILE__) . '/license.php';
require_once dirname(__FILE__) . '/defaults.php';
That should cover all the dirty work. From this point, everything is automated. Visit /public/upgrade/index.php part of your

activeCollab with your web browser, log in with your administrator credentials and let the system upgrade your database:

Now remove /custom/localization folder, because it's no longer needed (activeCollab 3 uses database to manage and store translations).
Clean URL-s
If you used clean URL-s tweak in activeCollab 2, don't forget to check out this article to learn how to update this tweak to make it
compatible with activeCollab 3. Note that this tweak may break your activeCollab 3 unless you upgrade it!
Final step is confirming that activeCollab is working by logging in. If you see log in screen, but you can't log in with credentials
that are known to work, please clean cache by removing all .php files from /cache folder.

Manual Upgrade (Instructions for activeCollab 3.0.x Users)


During activeCollab 3.0.x development, we stumbled upon a problem that activeCollab upgrade script can't resolve on it's own. In order
to work around this problem:
1. Open /activecollab/3.0.x/angie/classes/application/AngieApplication.class.php
2. Find bootstrapForUpgrade() method and replace it with:
/**
* Bootstrap for upgrade
*/
static function bootstrapForUpgrade() {
if(!(self::$adapter instanceof AngieApplicationAdapter)) {
self::loadAdapter();
} // if
self::initEnvironment();
self::initHttpEnvironment();
if(self::isInstalled()) {
self::initDatabaseConnection();
} // if
// --------------------------------------------------//

Get latest version number

// --------------------------------------------------$latest_version = null;
if($h = @opendir(ROOT)) {
$use_unpacked_files = defined('USE_UNPACKED_FILES') && USE_UNPACKED_FILES;

/**
* Return true if $version is valid angie application version number
*
* @return boolean
*/
$is_valid_version = function($version) {
if(strpos($version, '.') !== false) {
$parts = explode('.', $version);
if(count($parts) == 3) {
foreach($parts as $part) {
if(!is_numeric($part)) {
return false;
} // if
} // foreach
return true;
} else {
return false;
} // if
} else {
return false;
} // if
};
// Walk through files
while(false !== ($entry = readdir($h))) {
if($entry == '.' || $entry == '..') {
continue;
} // if
if($use_unpacked_files) {
$version = $entry;
} else {
if(str_ends_with($entry, '.phar')) {
$version = substr($entry, 0, strlen($entry) - 5);
} else {
continue;
} // if
} // if
if($is_valid_version($version)) {
if(empty($latest_version)) {
$latest_version = $version;
} else {
if(version_compare($latest_version, $version, '<')) {
$latest_version = $version;
} // if
} // if
} // if
} // while
} // if

// --------------------------------------------------//

Include upgrade utilities from the latest

//

available version

// --------------------------------------------------if($latest_version) {
require_once ROOT . "/$latest_version/angie/classes/application/upgrader/AngieApplicationUpgrader.class.php";

require_once ROOT . "/$latest_version/angie/classes/application/upgrader/AngieApplicationUpgraderAdapter.class.

require_once ROOT . "/$latest_version/angie/classes/application/upgrader/AngieApplicationUpgradeScript.class.ph


} else {
require_once ANGIE_PATH . '/classes/application/upgrader/AngieApplicationUpgrader.class.php';
require_once ANGIE_PATH . '/classes/application/upgrader/AngieApplicationUpgraderAdapter.class.php';
require_once ANGIE_PATH . '/classes/application/upgrader/AngieApplicationUpgradeScript.class.php';
} // if
AngieApplicationUpgrader::init();
} // bootstrapForUpgrade
When you are done, save the file and follow regular activeCollab 3.1.x upgrade instructions.

Tweaking the System


Different URL formats
activeCollab can use two different ways to generate URL-s:
1. http://example.com/public/index.php?path_info=projects/12 - In this case, path info goes as GET variable. This
increases compatibility with web servers (some versions of IIS, for example) that have problems with properly handling path info.
This method is default since activeCollab 2 beta.
2. http://example.com/projects/12 - System uses server's URL rewriting engine (mod_rewrite for Apache, for example) to
provide 100% clean URL-s. This method is not used by default, but you can follow these instructions to enable it for your setup.

Removing /public/index.php from URL-s


Compatibility Warning
This works with activeCollab 3.1 or newer, so please make sure that you have the latest version running.
By default, activeCollab will use URL-s containing /public/index.php in order to avoid having mod_rewrite as a system requirement. If,
from some reason, this system does not work (you get "No input file specified error" for instance) or you just want to have 100% clean
URL, then please follow the instructions bellow.
Create a file named .htaccess at the folder where activeCollab is installed, and add these lines:
Options -Indexes
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^(.+) - [PT,L]
RewriteRule ^assets/(.*)$ public/assets/$1 [L]
RewriteRule ^avatars/(.*)$ public/avatars/$1 [L]
RewriteRule ^logos/(.*)$ public/logos/$1 [L]
RewriteRule ^notebook_covers/(.*)$ public/notebook_covers/$1 [L]
RewriteRule ^template_covers/(.*)$ public/template_covers/$1 [L]
RewriteRule ^projects_icons/(.*)$ public/projects_icons/$1 [L]
RewriteRule ^proxy.php$ public/proxy.php [QSA,L]
RewriteRule ^sync.php$ public/sync.php [QSA,L]
RewriteRule ^$ public/index.php [QSA,L]
RewriteRule ^(.*) public/index.php?path_info=$1 [QSA,L]
</IfModule>
Now open config/config.php and update value of ROOT_URL to exclude /public from the end. If it was:
define('ROOT_URL', 'http://projects.example.com/public');
or:
const ROOT_URL = 'http://projects.example.com/public';

make it:
const ROOT_URL = 'http://projects.example.com';
After this declaration (not before, it will not work), add the following three lines:
define('URL_BASE', ROOT_URL . '/');
define('ASSETS_URL', ROOT_URL . '/public/assets');
define('PATH_INFO_THROUGH_QUERY_STRING', false);
Final step is to clear the cache, so activeCollab can pick up new URL-s instead of using old, cached ones. To clear the cache, use your
FTP client and navigate to /cache folder of your activeCollab and remove all .php files that are stored there.
That's it. To test, navigate through your activeCollab and check if links are updated.

1. Importing Rewrite Rules in IIS7


IIS7 rewrite module features a tool that lets you easily import Apache mod_rewrite rules. Please check this article for details:
http://learn.iis.net/page.aspx/470/importing-apache-modrewrite-rules/

2. Rewrite Rules for nginx


If you are using nginx web server, please use following the rules:
if (!-e $request_filename) {
rewrite ^avatars/(.*)$ /public/avatars/$1 last;
rewrite ^logos/(.*)$ /public/logos/$1 last;
rewrite ^notebook_pages/(.*)$ /public/notebook_pages/$1 last;
rewrite ^projects_icons/(.*)$ /public/projects_icons/$1 last;
rewrite ^proxy.php$ public/proxy.php last;
rewrite ^sync.php$ public/sync.php last
rewrite ^$ /public/index.php last;
rewrite ^(.*) /public/index.php?path_info=$1 last;
}

/public Folder as Document Root


activeCollab is designed to be simply dropped in a subfolder and installed. On the other hand, you can have a bit more advanced setup
where only content of /public folder is publicly available while everything else is behind the document root and inaccessible. To
demonstrate this other type of setup, we'll have a virtual host defined that maps http://intranet to public folder of our activeCollab
setup:
<VirtualHost *>
ServerName intranet
DocumentRoot /Library/WebServer/Documents/intranet/public
</VirtualHost>
Content of /intranet folder looks like this:

In order to install activeCollab, we'll simply visit http://intranet. activeCollab will present simple installer utility that you can use to get
activeCollab database and initial data created. When installer shows us that activeCollab is successfully installed, everything should be
working just fine even though only /public folder is publicly available.
When you confirm that system is running properly, open config/config.php and add the following line to the block where all other
configuration options are defined:
define('PUBLIC_AS_DOCUMENT_ROOT', true);
Please note:
1. Sometimes the document root folders are not named public (frequently it is public_html, web etc). In that case, put the content of
/public folder in your document root, run the installer and when you're done open config/config.php and make sure that
PUBLIC_FOLDER_NAME is set to the correct value.
2. If you are using .htaccess fix to have 100% clean URL-s, then you'll need to put it in /public folder and make appropriate changes
to rewrite rules.
3. Folders like /cache, /upload, /logs, and so on, are protected by .htaccess file with rules that restrict direct access to files located in
these folders. Your server will need to be configured so it allows overriding using .htaccess files. Read more in Apache
documentation.

How to Increase Maximal Upload Size?


activeCollab does not limit the size of files that can be uploaded. Limitations are enforced by your web server, and activeCollab will
only displays current limit on forms that allow file upload:

To increase the max upload size, open php.ini file and change values of upload_max_filesize and post_max_size directives to value that
suits your needs. For example:
upload_max_filesize = 64M
post_max_size = 64M
Save php.ini and restart your web server. If you don't have access to php.ini, contact your system administrator or hosting provider
to increase these values for you and point out that they need to be applied to /public folder. Don't forget to restart your server after the
changes in the php.ini are made. If you skip this step the maximal upload size change will not be applied.

Apache Note
Apache has a LimitRequestBody configuration directive. It restricts the size of all POST data regardless of the web scripting language in
use. You might need to update this value, too.

Improving Search Index


By default, activeCollab uses MySQL FULLTEXT index for search. It works great, but in some cases MySQL can be configured not to
index words shorter than 4 characters. To correct this and configure MySQL to index 3-letter words (it's not recommended to go with
shorter than 3 chars), you will need to set the value of ft_min_word_len directive in your my.cnf:
[mysqld]
ft_min_word_len=3
After you are done, restart your MySQL server and rebuild search indexes using Indexes tool on Administration page of your
activeCollab:

Moving activeCollab to Another Server


If necessary, you can move your activeCollab setup to another server at any time.
Before you start moving your activeCollab installation, please make sure that your new server is meeting system requirements needed
for activeCollab to run smoothly.

1. Requesting a New URL


This step is necessary only if you wish to change the URL of your activeCollab. If canse you want to keep the same URL,
please skip and move forward to the #2.
To change the URL of your activeCollab instance, you will need to ask for URL change on your activeCollab.com profile page.
To do that, follow these steps:
1. Login using your activeCollab.com username and password;
2. Click My activeCollab button;
3. Use Change link next to license URL on the main profile page

URL change is automated. Only in case you have asked for URL change 3 times in a row, you need to wait for a manual
approval.
After you receive an email that your URL is changed, please download the license.php from our website and replace the
existing one in your activeCollab setup.
Don't forget to clear /cache and /compile folders after the license.php replacement.

2. Installing activeCollab on a New Server


All you need to do now is to install a fresh copy of activeCollab on your new server. You can get activeCollab files on your
www.activeCollab.com profile page.
Note
Make sure that you use the same table prefix that you used for original setup (usually it is "acx_").

3. Moving Data from the Old Server


Now you are ready to move the data from old setup - you have the new URL and a fresh copy of activeCollab installed.
1. Move your activeCollab database
Here's what you should do to make this process safe and sound:
go to your setup on a new server and drop all activeCollab tables that installer created;
now export tables and data from the old setup;
import it into a new database.
You can do this by using your favorite MySQL administration tool (phpMyAdmin, command line MySQL client, Navicat etc).
The choice is yours.
Database moving video
This short video (QuickTime Movie, 2MB) shows how can you do this in a three simple steps using phpMyAdmin: select
database, on export tab make sure that all activeCollab tables are selected, and save them as file.
After the migration process of database tables from old setup to the new one is completed, you should move the content of
the following folders to the new server:
/public/avatars
/public/logos
/public/notebook_covers
/public/projects_icons
/upload
activeCollab stores your binary data in those folders - images, uploads, etc, so don't forget to move them,
too.

Transfer Mode

When uploading images, avatars etc from your old setup, make sure that you use Binary transfer mode in your
FTP client. Using ASCII mode may result in corrupt files afterwords.

2. Upgrade your database


Now that files are moved, please check permissions and make sure that existing files are writable by PHP. If these
files are read only, you'll not be able to update them.
Next thing to do is to upgrade your database (this is just in case that your database is not the latest activeCollab version). to
do that please visit /public/upgrade/index.php part of your activeCollab with your web browser. Log in with your
administrator credentials and let the system upgrade your database.

3. Rebuild indexes and cear cache on the first run


After you log in to your activeCollab with restored data from the old server for the first time, rebuild the images and empty
the cache from the admin menu at the bottom right corner in the interface. You can do that by using the Control Tower tool.
This is all you need to do. If the process is went fine you will enjoying your old activeCollab setup in a new environment in no
time.
If you have any questions or you have experienced any problems with moving your activeCollab, please do not hesitate to
contact our support team at support@a51dev.com.

Troubleshooting
Debugging
activeCollab can run in two different modes, based on the value of APPLICATION_MODE directive. Possible values:
1. in_production_mode - default mode used for system in production environment. In case of a system error, activeCollab
displays a brief error message to the user without reveling any sensitive system information and sends an email notification to the
administrator, with all relevant information included. Recipient for this kind of notification is configured with ADMIN_EMAIL
directive.
2. in_debug_mode - debug mode used for troubleshooting and development. In this mode activeCollab logs entire execution
process in /logs folder. Logged information are grouped by day. In case of a system error, detailed error with all relevant system
information is displayed to the user, but no email will be sent.
When troubleshooting, you should set APPLICATION_MODE to in_debug_mode. Open config/config.php and change the value of
APPLICATION_MODE to in_debug_mode. If APPLICATION_MODE directive is not present in config/config.php, then you can add it
yourself by adding the following line to the file:
define('APPLICATION_MODE', 'in_debug_mode');
It is strongly recommended that you use debug mode only for debugging. When you are done debugging, remove APPLICATION_MODE
from config/config.php file to avoid revealing any sensitive information about your activeCollab setup.

Some of the Icons and Images are Missing


After installation or upgrade, activeCollab copies all assets (images, Flash files and fonts) to /public/assets folder. If some elements
are missing, than it usually means that rebuild assets operation did not work properly.
To work around the problem, please try to run Rebuild Assets tool from Administration menu:

If that does not help, follow this procedure:


1. Connect to the server where your activeCollab is installed using your FTP or SFTP client, and navigate to /public/assets folder of
your activeCollab setup,
2. Clear all subfolders in that folder,
3. Confirm that /public/assets has proper permissions (PHP can write in that folder, and it can write in subfolder is creates in it),
4. Run Administration > Rebuild Assets tool again.
In case that this operation fails, problem is in permissions, so double check step #3 of the process.

Testing if Emails are Sent Properly

Emailing is one of the most important features of activeCollab. In this article you'll find instructions on how to check if emailing is
working properly and how the emails sent by the system look like.

1. Configuring Email and Sending Test Message


First thing that needs to be done is to check if activeCollab can connect to the server and send out an email.

There are two ways in which activeCollab sends emails:


1. Using Native Mailer. In this case, activeCollab will use mailing server configured in your php.ini file. If PHP is
properly configured, system will connect to it automatically without any additional parameters.
2. Using SMTP server. System connects to SMTP server by using built in system and sends out the messages.
After successful installation, Native Mailer is selected by default, so mailing should work properly if it is configured in
php.ini. If it is not configured, you'll need to provide SMTP connection parameters. To check if SMTP parameters you have
provided are good and system can connect to the server, use Test Connection button on Mailing page.
When you have configured mailing on Administration > Mailing page, next thing you should do is to send out test
emails. There is a tool available in Administration called Test Mailing Settings. Using this tool, you can write a message
and send it to specified address. If everything works properly, you have successfully set the mailing up.

2. Testing Email Notifications


When email is configured properly and messages sent using Test Mailing Settings tool are sent properly, you may wish to
see how notifications sent by activeCollab look like. To do this, you'll need two separate user accounts. Reason for this is that
activeCollab does not send notifications to person who executes the action.
If, for example, you post a comment to a ticket you'll not receive a notification about it even though you are subscribed. You
posted the comment so there is no need for system to notify you. On the other hand, all other subscribers will receive email
notifications.
To test notifications, create a new ticket and select other account you use for testing as assignees. When ticket is created,
email with the details about it should be sent to other user account you used for testing.

File and Folder Permissions


The most common cause of problems within activeCollab is file and folder permissions. Improperly set permissions can result in various
issues:
Blank pages when you try to use the system;

Users unable upload and attach files;


User avatars, company logos, notebook covers or project icons do not work as expected;
Project exporter is not able to export content;
Backup module is not able to create backups,
Upgrade script fails to write information about the latest version etc.
To resolve these issues, please make sure that PHP can write to all the folders and files listed below. These folders need to be writable
for activeCollab to work properly:
/activecollab
/cache
/compile
/config/version.php
/logs
/public/assets
/public/avatars
/public/brand
/public/logos
/public/notebook_covers
/public/projects_icons
/thumbnails
/upload
/work

Solving Memory Problems


PHP limits the amount of memory given for execution of a script. This is controled by memory_limit configuration option.
By default, memory_limit is set to 8MB. If the script tries to allocate more memory, PHP will display a fatal error that looks something
like this:
Fatal error: Allowed memory size of N bytes exhausted (tried to allocate M bytes) in FILE on line #.
To get around this error, you will need to increase PHP memory limit and make more room for executing the application.
Open php.ini file, find a line where memory_limit option is defined and change it to a higher value. Although 8MB is enough for most
activeCollab requests, in some cases activeCollab will need more memory, especially when working with images. Because of that, we
recommend memory limit to be set to 64MB. The line where memory limit is defined will look like this:
memory_limit = 64M
When you make the change, save php.ini file and restart your web server.
Note
On some servers you will not be able to change php.ini file by yourself. In that case, please contact your system administrator or hosting
provider in order to make this change for you.

1. Problems with Memory and Image Thumbnail Creation


Thumbnail creation for images was introduced in activeCollab 1.1. It is enabled by default and resizes images (JPG, GIF and
PNG only) smaller than 1MB so users can see a preview without downloading original file. This was causing problems on
some setups where recommended 64MB memory limit was not high enough for resize operation to be performed.
Fix was introduced in activeCollab 1.1.1. From this release you can set max size of images that will be resized (default is
500kb) or completely turn off thumbnail creation. You can define two new configuration options in your config/config.php:

1. CREATE_THUMBNAILS - True or False, enable or disable thumbnail creation. True by default.


2. RESIZE_SMALLER_THAN - If CREATE_THUMBNAILS is set to true this option defines maximal size in bytes of
images that can be resized. Default is 524288 (500kb). Larger images will be ignored. Here is how it would look like in
your config/config.php if you wanted to have thumbnails enabled for all images smaller than 1MB:
define('CREATE_THUMBNAILS', true);
define('RESIZE_SMALLER_THAN', 1048576);

Resolving "Failed to connect to database" Crashes


activeCollab is dependent on database where it stores your project data. If it fails to connect to the database, it will send a crash report
to administrator or display an error message when system is in Debug mode.
Although pretty rare, first option is that your database connection parameters or database name have been changed since you set up the
system. To resolve this, open config/config.php and update connection parameters:
define('DB_HOST', ''); // MySQL server hostname, usually localhost
define('DB_USER', ''); // User that you're using to connect to database
define('DB_PASS', ''); // User's password
define('DB_NAME', ''); // Name of the database where activeCollab is installed
More likely scenario is that your database is just temporally unavailable.
Database may be unreachable for many reasons: MySQL server is down or restarting, maximum number of open database connections
is reached and activeCollab's request to connect was rejected, etc. All of these situations are outside of application's control
and can't be fixed by activeCollab, so it simply ends execution and sends or displays a crash report.
If you are receiving these crash reports frequently, we recommend that you contact your hosting provider and ask for
assistance.

Fixing Crashed or Corrupt MySQL Tables


MySQL is software like any other running in a complex environment. It is known for its stability, but sometimes tables may crash or get
corrupt from various reason.
When something like that happens, you will get crash reports with information that query failed because of missing file or invalid
information in one of the files. Exact error messages may very and here is just one example:
Query failed with message 'Incorrect information in file: './db_name/ac_user_sessions.frm''
First step that you should take if you start receiving such crash reports is to try to repair the table. Here's how you can do that with
phpMyAdmin:
1. Log into your phpMyAdmin and navigate to database where you have activeCollab installed
2. Select table that crashed by clicking on checkbox in front of its name, and than select Repair table option from drop-down at the
bottom of the tables list:

If Repair command fails to resolve the problem, you should contact your hosting provider or system administrator for assistance.