conjoon Documentation

Index

This documentation relates to conjoon 0.1.5

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 "myhost.com", {SERVERNAME}/path would refer to "myhost.com/path".
    (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.

Error:
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.

Welcome

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

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

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

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 127.0.0.1 here.

Database port

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

Database

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

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

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

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.

Step 7

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 8

(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.

Patching

(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.

Install!

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.

Finish

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.

 

The installation.info.php-File

All data applied to conjoon during the setup process will be collected and stored in the "installation.info.php" 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.

 

Labels: