This documentation relates to conjoon 0.1.6

If your are using an earlier version, please view the previous versions of the conjoon documentation and select the relevant version.

Skip to end of metadata
Go to start of metadata

After installing or updating the conjoon files, you need to run the setup first before you can start working with conjoon.

Upgrading to a newer version of conjoon?

If you are upgrading to a newer version of conjoon, please continue with the conjoon Upgrade Guide instead.


The setup guide assumes that you have updated or installed the conjoon files and

  • you already have a virtual host configured. In this guide, we will refer to the ServerName of your virtual host with the placeholder {SERVERNAME}. Additionally, we will refer to your virtual host's DocumentRoot with the placeholder {DOCROOT}
    (info) If your ServerName's value is "", {SERVERNAME}/path would refer to "".
    (info) If your DocumentRoot's value is "/var/www/hosts/myhost/htdocs", {DOCROOT}/path would refer to "/var/www/hosts/myhost/htdocs/path".
  • you are going to install conjoon in {DOCROOT}/webmail and therefor want to access it at {SERVERNAME}/webmail.


When visiting {SERVERNAME}/webmail with your browser, you should see a message that you need to run the setup process first.

config.ini.php not found. Run the Setup Assistant or create it manually.

When using an opcode cache like APC, make sure you disable this cache for the setup process, and clear the cache once the setup process has finished.

On this page:

The Setup Assistant

Due to historical reasons, a lot of guides refer to the Setup Assistant as the "Install Wizard", or "Setup Wizard". Whenever we refer to "Install Wizard" or "Setup Wizard", we mean "Setup Assistant".

The Setup Wizard consists of a series of screens which all gather informations related to the configuration of the conjoon instance. Additionally, each screen gives you some navigation elements and further information about your current position in the setup process.

Screenshot above: A configuration screen of the setup wizard.

The Setup Tabs

The Setup Tabs are a series of tabs positioned at the top of each screen. Tabs are named after the task their corresponding screen represents - common configuration options are named "Step n", where n is a number ranging from 1 to 7.

Your current position in the setup process is highlighted - a tab would then have a brighter background as the remaining tabs.

The Previous/Next Buttons

You can navigate between the various configurations screens by using the Previous/Next Buttons. Pressing the Previous Button will take you one step back in the setup process so you can review previously specified configuration options again.

Pressing the Next Button will invoke a check of the configuration options specified in the current screen, and either show error messages if any configuration options is lacking or erroneous, or taking you to the next screen to continue with the setup process.

The Configuration Screen

Each Configuration Screen will introduce it's task to you by an informational message, then providing various input fields for configuring your conjoon instance. Configuration Options can be validated and saved by pressing the Next Button.

Configuration Options will not get applied once the Next Button has been pressed. before applying all of the gathered configuration options, the "Finish" Screen will present you all gathered configuration options for reviewing them. During the Setup Process, you do not need to worry about any changes made to your system.

Running the Setup Assistant

The following describes each step from the Setup Wizard in the order appearing during the setup process.

Once you have installed or upgraded the conjoon files, you should open the address {SERVERNAME}/webmail/install.

Before you can start the Setup Assistant, you need to specify a secret key which will help conjoon in identifying you as a valid user authorized to setup conjoon. To do so, you need to:

  1. Navigate to {DOCROOT}/webmail/install and edit the file SETUP_AUTHORIZATION_KEY.ini.php found therein.

  2. Thils file holds a property named CONJOON_AUTHORIZATION_KEY, which has to be adjusted to a secret value only known to you. In the following example, we will set the value to "my83instM".

  3. Save the changes made to the file and open {SERVERNAME}/webmail/install. You will see the Setup Assistant's Authentication Screen now.

  4. In the "Key" field, type in the secret key you just provided, then click the Submit Query button next to the field. The Setup Assistant will now authenticate you against the secret key found in the SETUP_AUTHORIZATION_KEY.ini.php file. If the provided key matches the one found in this file, you can start with the setup process.


The Setup Wizard will load and guide you through the steps necessary for configuring you conjoon instance.

The Welcome Screen is the first screen shown to you. It presents some informational messages and checks whether a previous installation of conjoon was found and - based on that - preload all previous configuration options so you don't have to specify them again in the following screens.

It will also require you to acknowledge that you have read and understood the license under which conjoon was published, and that you are aware of the fact that now would be the best time to create a backup of existing data which could in any way be affected by a conjoon installation. Once you have confirmed both options, you can press the "Next Button" to go to the next screen.

Step 1 - Validating prerequisites

Before conjoon continues with gathering configuration options, it will check if all prerequisites for running a conjoon instance on your system are matched. This involves checking the System Requirements, but also some PHP and Apache configuration settings.

If the setup screen shows any warning or error, you should read through to the chapters

to know how to setup your system to work with conjoon.

Please make sure that the installed/updated files and folders you have deployed during the installation/upgrade process are writeable by your web server. If the setup process does not have write access to the folder it is located in and the corresponding parent folder, you will not be able to continue with setting up conjoon.

Step 2 - Localization

This step gathers locale information for the conjoon application.

You have to provide an application's timezone for conjoon, and a fallback timezone.

Application's Timezone

conjoon converts all dates to the UTC time zone before persisting them. For proper calculations when presenting dates belonging to various entities to the user, conjoon needs to know which time zone it should serve. Choose any appropriate value from the combo box. Example: If you're using conjoon in Germany, choose Europe/Berlin as the application's timezone.

Fallback Timezone

A fallback timezone is needed in case the Application's Timezone is erroneous or not readable. It will get written into the application's bootstrapper file during the setup process and should be set to the same value as the Application's Timezone.

Please make sure that the date and timezone settings of your underlying operating system are configured properly. See Date and Timezone Settings for more information.

Step 3 - Setting up the database

This step will collect information related to the database backend you're using with conjoon. Once you have provided all the necessary information and press the Next Button, conjoon will try to connect to the database. If this fails, an error message is presented to you and you will not be able to continue the setup process until teh database settings have been validated.

Make sure the dabase you want to use with conjoon is already existing, since conjoon will not try to create a new database. See also the chapter Preparing the Database for conjoon.


Database host

The host where the databse runs on. (info) If the database runs on the same host as the web server, you can most likely provide the value localhost or here.

Database port

The port the database server listens to. (info) When using MySQL as the database backend, the default port would be 3306.


The name of the database that should be used with conjoon. This database must already exist.

Table prefix

A prefix for the tables conjoon uses for persisting data. This is useful if you only have one database available which is already used by another application. To prevent overriding data in tables that share the same name, you can provide a prefix for the conjoon tables here. Example: conjoon uses a table named "users" for storing user relevant data. If you choose no prefix, the table "users" will be created/used under the name "users". If you choose to use a prefix "cn_", conjoon will create/use this table under the name "cn_users".

When upgrading conjoon, the Setup Wizard will reuse all information provided in recent setup processes. If you choose to change the table prefix from an existing prefix (or no prefix at all) to a different prefix, conjoon will create new database tables based on this new prefix, ignoring the tables previously used with conjoon. Previously persisted data will not be available after the update then.

Database user

The database user to use with database authentication.

Database password

The database password to use with database authentication.

Max allowed packet

The largest size of a communication packet the database server can process, in bytes.

You do not need to specify this value. If omitted, conjoon will determine the setting from the database backend you are using.

This setting is useful if your database server allows a rather large number of bytes for a single communication packet, but you want to narrow this number down. (info) Data exceeding this size will not get written into the database, and in this case conjoon will generate warnings to inform the user about this. If you're frequently handling large email messages, you should set this to a high enough value. See Preparing the Database for conjoon for more information.

Step 4 - Installing the application folder

This step lets you provide the path where all application relevant data gets stored. Application relevant data would be templates, controllers, and cache data. Make sure the path you provide is readable and writeable by the web server, but not accessible from outside due to security reasons.

(info) If you omit this value, conjoon will store the application data in the document root of the conjoon application, which is not recommended.

Step 5 - Cache Settings

You can either enable or disable chaching of data globally here, or enable caching and enable/disable cache per module.

Enable Cache

Either set this value to "Yes" or "No". If set to "No", subsequent configuration options will be hidden and you can continue to the next setup step by pressing the Next Button.

If set to "Yes", you can specify cache settings per module.

Each module and it's cache options allow for specifying a separate cache path where data gets stored. If you do not specify cache paths, conjoon will reuse the application path specified in Step 4 and use this as the base path for caching. Calculated paths are then presented to you in the individual text fields of the modules where you can edit them at will.

Database Cache

The database cache caches metadata of database tables. This speeds up the creation of database objects under the hood of conjoon.

Email Cache

Allows for specifying if messages and accounts should get cached. Cached messages allow for faster access to messages which have already been read. Caching email accounts will speed up read access to these accounts. The cache can also save informations related to root folder types, which will increase the time looking up this information during the runtime of a conjoon session.

Feed Cache

Allows for caching data related to various feed operations. Will generally speed up loading feed items and accounts, and prevents connections to be made to attached feed sources if no update was detected.

Twitter Cache

Caches Twitter accounts which will speed up communication with the Twitter service by reducing network connections, since account information will not be renewed on each and every request.

Step 6 - Library specific Settings


HTMLPurifier is used to sanitize HTML content from external resources, such as incoming mail.

Preload HTMLPurifier library files

Set this to 'yes' to preload the HTMLPurifier libraries. This should result in a performance increase on systems which are using opcode caches, such as APC.

Enable cache

Enabling the cache will speed up text based operations. It is recommended to use the cache.

Path to HTMLPurifier cache

Only available if Enable Cache of the HtmlPurifier settings was set to 'yes'. Provide the path to the directory where HTMLPurifier cache files should be stored.


Doctrine is the object-relational mapping framework used by conjoon.

Enable cache

Increase performance by enabling Doctrine's cache. The following settings will provide various cache container options based on the availability of those on the target system.

Enable Cache: "Query Cache"

Enable Doctrine's Query Cache to increase performance and choose the cache container. Options are:

  • apc
  • memcache
  • memcached
  • file

(info) If any of the tools (such as apc) was found on your system, those related options will be enabled, otherwise disabled.

Enable Cache: "Metadata Cache"

Enable Doctrine's Metadata Cache to increase performance and choose the cache container. Options are:

  • apc
  • memcache
  • memcached
  • file

(info) If any of the tools (such as apc) was found on your system, those related options will be enabled, otherwise disabled.

Step 7 - Application Configuration Settings

File Storage Settings

This allows to configure various options related to file uploads and how they should be treated by conjoon.

Max. Upload File Size (in bytes)

Set the max. allowed upload file size in bytes here. This value should be the minimum value of max. allowed packet (as configured in Step 3) and your php's post_max_size/upload_max_filesize.

Enable Filesystem

Choose whether you'd like to save file uploads in the database or in the file system. While it's largely depending on your server hardware and environment, access to file uploads saved directly to the file system might be faster on smaller systems.

Path to Filesystem Storage

If you have chosen to enable uploads to the file system instead of the database, this step let's you specify the base folder where uploaded files should be organized by conjoon.

Step 8 - Installing the libraries

Provide the base path for the PHP libraries. Make sure the path you provide is readable and writeable by the web server, but not accessible from outside due to security reasons.

 (info) If you omit this value, conjoon will store the libraries in the document root of the conjoon application, which is not recommended.

You can choose if you'd wish to let conjoon take care of setting the include path. If you provide include path settings in your webserver configuration, please note the following:

Due to the way HTMLPurifier organizes its files, the include path which gets computed out of the provided library path in Step 8 - Installing the libraries will be edited internally to the following value:



be the value you have provided as the include path. The include path will then be adjusted to 


The HTMLPurifier library has to be taken into account. Thus, the include path will automatically get adjusted to


Always remember to add the path to the HTMLPurifier library files if you adjust the include path on your own.

Step 9 - Specifying the document path

Specify the document path here.

The document path is the "base url" where conjoon can be found. Example: When installing conjoon at {SERVERNAME}/webmail,"/webmail" would be the document path. conjoon will try to auto-detect the document path.

Step 10

(info) This step is only available if you do a fresh install of conjoon.

Specify the user credentials for the conjoon administrator of conjoon here. Make sure you choose a secure password and avoid combinations like "abc", "123" and so on.


(info)This step is only be available when upgrading conjoon.

If there is a change in conjoon's codebase or in the data structure conjoon's using, a patch will most likely be available that is presented to you here. A patch allows for upgrading to new versions of conjoon while making sure that data managed with previous versions can still be used. Not every version introduces a patch, so you might see the "Patching" screen only once in a while.

Screenshot above: The Setup Assistant providing a patch during the setup process.

Follow the steps described on the patching screen if patches are available, and make sure you apply the patches during upgrading. (warning) Not applying patches can negatively affect your conjoon installation.


This screen sums up all the information conjoon has gathered during the setup process. Please review this information now and go back to any previous screen if you would like to change a setting.

Once you have pressed the Next Button, conjoon will start to remove all files associated with the current installation (if any) and replace them with the files from the new version. Once all data has been installed/updated and - if applicable - patches have been applied, conjoon will redirect you to the Finish screen.

Depending on your system's hardware setup, file operations may take a while. iIt is therefor recommended to make sure that your PHP environment grants scripts a long enough execution time. However, on most systems a max_execution_time of 30 seconds should be sufficient for the final setup process.


Shows an informal message that the setup process has finished. You should now delete the "install" folder from {DOCROOT}/webmail. Once this is done, you can open {SERVERNAME}/webmail and start using conjoon.

You can view some log information related to the setup process by looking up the file named "INSTALL_LOG_[Y.m.d-H.i.s].log" in your "install" directory. Do so before you remove this folder.



All data applied to conjoon during the setup process will be collected and stored in the "" file which will be stored in the document root of your conjoon installation (in our example in {DOCROOT}/webmail). conjoon will use this file during future updates and determine which settings have been used in previous installations, and if any patch was ignored during previous upgrades. It is recommended that you keep a backup of this file and use this file throughout future upgrades as long as you do not wipe your attached data storages data. (info) No passwords will be stored in this file.