1.1 Types of installation
There are different installation packages for Communote:
Installation with system integration script
Tested with chosen Linux distributions. It contains a script which supports the system integration of the installation. This installation package already contains a Java Runtime Environment, therefore there is a 32 and 64bit version
Installation without system integration script
Available for Linux and Windows.With this package you can start Communote without special configuration. However you have to install a Java Runtime Environment before installing Communote In case you are not sure if the system integration script is working on your platform use this installation package.
Installation by WAR-File
Using the installation by a WAR-File the complete configuration must be done by hand. The installation by WAR-File should only be done by experienced users.
To download the various packages or upgrade to a new version, visit the download area of our homepage www.communote.com/homepage/download/.
The following hardware requirements are recommended:
- 64bit Dual core system
- 10 – 100 GB data storage (The actual size depends on the usage of the file upload option. The actual installation data size is less than 1 GB.)
- 2 GB Ram
At the moment the following database systems are supported:
- PostgreSQL 9.0, 9.3 (recommended)
- MySQL 5.0.57 or newer 5.0 Version, 5.1 (recommended)
- MS SQL Server 2008 r2
- MS SQL Server 2012
- Oracle 11g
It is recommended to run an Apache HTTP server for serving requests to the Communote installation. This server should fulfill the following requirements:
- Apache Version 2.2.5 or higher, with the modules mod_proxy, mod_proxy_http and mod_proxy_balancer
Before starting the installation you have to prepare a database that Communote can use. At the moment MySQL and PostgreSQL are supported. Please install one of these database systems and create a new database schema for Communote.
Create a MySQL Database:
Remark: For using MySQL with Communote you have to download the MySQL JDBC Driver yourself (Version 5.1.14): http://dev.mysql.com/downloads/connector/j/ and copy it into the communote\lib directory. In case you are installing Communote by WAR file you have to copy the library directly into the lib directory of the Tomcat installation. You can create a database with the MySQL command line tool. First open a console and change to the bin-directory of your MySQL server and connect to your database server (replace root and mysqlpwd with your username and password):
Now you are in the SQL Shell of MySQL and you can enter SQL statements e.g. for the database creation. Every SQL statement has to end with a semicolon (;). The Shell can be closed by entering the command exit.
First create a database for Communote. Replace communote_db_name with the name of the database for Communote to use:
With the command SHOW DATABASES; a list of all databases will be shown and you may check if the database has been created successfully. For security reasons a separated database user should be created and the database access to the Communote database should be limited. To do this execute the following statements in the MySQL Shell and replace communote_db_name, communote_db_user and communote_db_password with the database name, the database user and the database password. Replace also IP_COMMUNOTE_SERVER with the IP of the Communote server and copy and paste this line if you need other severs to access the database as well (e.g. for administrative access):
Create a PostgreSQL Database:
Remark: In case you are installing Communote by WAR file you have to download the PostgreSQL JDBC driver from http://jdbc.postgresql.org/download.html and copy the JAR file to the lib directory of your Tomcat installation. Because Communote does not support PostgreSQL versions prior to version 9, you have to use a 9.x-y JDBC driver (recommended: latest stable 9.3-y JDBC driver).
Go to the PostgreSQL shell:
It is recommended to use a separate database user with rights to access the communote database. You can create a new user with the following statement in the PostgreSQL shell, replace communote_db_username and communote_db_password with the name of the database user and the password:
The database can be then created with:
You now can leave the PostgreSQL shell by entering „\q".
Create a Microsoft SQL Database
Remark: For using MSSQL with Communote you have to download the JDBC Driver yourself: http://jtds.sourceforge.net/ and copy it into the communote\lib directory. In case you install Communote by WAR file you have to copy the library directly into the lib directory of the tomcat.
Creating a Database with the Microsoft SQL Server Management Studio:
Create the Database
- New Database
- Assign a Name
- set Options -> Collation to Latin1_General_100_CS_AS
Figure 1 1: Create Database
Figure 1 2: Database Options
Create User and assign permissons
- Security -> Logins -> New Login
- Login Name
- SQL Server authentication -> Password
- Default Language: English
- User Mapping
- Communote DB
- give db_owner permissions
Figure 1 3:Create User
Figure 1 4: User mapping
Install the Full-Text Search Instance Feature.
At the end run the Installer.
Create an Oracle Database
Remark: When using an Oracle Database you have to download an appropriate JDBC Thin driver from http://www.oracle.com/technetwork/indexes/downloads/index.html (Drivers section) and copy the JAR into the Communote\lib directory. The driver to choose depends on the version of your Oracle Database and Java. For instance with Oracle Database 11g Release 2 (18.104.22.168.0) and JDK 7 you will need the driver listed as 'ojdbc6.jar'. In case you are doing an installation via WAR file, the JDBC Driver must placed in the lib directory of your Tomcat installation. For information on installing and configuring an Oracle 10g and 11g database see the Oracle database documentation for 10g or 11g which can be found under http://www.oracle.com/pls/db102/homepage or http://www.oracle.com/pls/db111/portal.portal_db?selected=11 respectively. Note: the character set has to be "AL32UTF8".
You should also create a new user schema as outlined below:
1.3 Installation with the Installerscript for Linux
Remark: The installer script has been only tested on a Gentoo (up to date configuration as of Q3 2010) and for Ubuntu 10.04 LTS. You should only use the installer script for those distributions. Also make sure that your system has a current version (at least 4.1.3) of the shadow package installed.
For Linux distributions an Installer is available which will ship with all necessary components for Communote to run and configure them initially. The installer will also include the required Java Runtime Environment (JRE). Using Linux you can download the installer with the command line tool wget. You will find an up-to-date version on the Communote homepage:
After downloading the installer you can unpack the installer. By default the command is:
Now change into the directory of the just unpacked files and execute the following command:
Follow the instructions of the installer. It will go through the following steps (For every step default values will be suggested. You may accept them by just pressing the return key):
- User und group: Here you can define a user and group to be used as owner for the files to be installed. If user or group do not exist they will be created.
- Port: Here you can specify which port the application should use. If the port is currently used, the installer will give you a warning. You should then choose a different one.
- Installation directory: Enter the installation directory. The application and necessary components will be installed into this directory.
- Data directory: Enter the data directory for Communote. In this directory the configuration data, cache data and by default the attachment repository will be stored here. Please assure to have enough disk space available for this directory since attachments will be stored there by default. The default value for the data directory will be a sub directory of the installation directory.
After completing the installation check:
- Communote has been installed in the correct installation directory and
- The file system rights have been set correctly on the provided data directory.
At the end of the installation procedure Communote will be started and you can continue with the installation using the web interface (see section 1.8 ).
1.4 Installation without Installerscript
For an installation without the installer script you will have to use one of the packages without the JRE (see section 1.1.). Use the tar.gz on Linux and .zip on Windows platforms. To install Communote from these packages follow the instructions below:
Download and install the latest Oracle Java Runtime Environment (JRE) of version 7 (http://www.java.com/en/download/). After the installation of Java check that the correct version is returned when executing the command:
- Unzip or untar the downloaded package into an arbitrary directory. This directory now contains among others a directory named communote which you copy into your preferred installation directory (COMMUNOTE_INSTALL_DIR).
- When not using a PostgreSQL database download and install the appropriate JDBC driver for your database as described in the previous sections.
Define the Communote configuration directory. Edit the file COMMUNOTE_INSTALL_DIR/communote/conf/context.xml and add the following entry in between the elements <context> and </context>. We suggest that you use the prepared configuration directory COMMUNOTE_INSTALL_DIR/communote/conf/communote
- Configure the data directory which Communote will use for storing application data. This directory will also be used as the default location for saving attachments.
- Create a file called startup.properties in the Communote configuration directory.
Add the absolute path to the data directory to the startup.properties file as shown in the following example. The example defines C:\Communote\Data as data directory. You should not select a directory within COMMUNOTE_INSTALL_DIR/communote/communote/ because this would allow unauthorized users to access the content of that directory directly from their web browsers.
Note: Use the slash character instead of a backslash as path separator on Windows. Colons have to be escaped with a backslash.
- Optional for Linux systems (recommended): Create or select a special user without root access that should be able to run Communote. This user must have read and write access for the data directory and should be the owner of the Communote installation directory.
- Now you are ready to start Communote. To do this, go to the directory COMMUNOTE_INSTALL_DIR/communote/bin and run Communote with startup.bat or startup.sh (as the correct user).
Continue the installation with the web interface (see section 1.8).
1.5 Installation as WAR
You can install Communote without the predefined packages. However, this is only recommended for experienced users. You have to execute the following steps (Note: For the installation of the required software please use the installation guides of the corresponding software vendors):
- Download and install the latest Oracle Java Runtime Environment (JRE) of version 7 (http://www.java.com/en/download/). After the installation of Java, check the installation by executing the command: java -version
- Download the latest version of Tomcat 7 (http://tomcat.apache.org/download-70.cgi) and install it. In case you want to use a Tomcat 6 it has to be at least version 6.0.29.
Edit the files
context.xml, so that every
context-Element has the paramter
- Download and copy the appropriate JDBC driver for your database into the lib directory of your Tomcat installation as described in the previous sections.
- Download the latest version of Communote as WAR file (communote.war) und copy it to the webapp directory of the Tomcat. Important: Rename the WAR File as "ROOT.war". Please mind the case. By default Communote is configured to be run in the servers ROOT context. To run Communote in another context you will have to adjust the server settings in the Communote administration after the installation. The required steps are outlined in section 2.1 of the administration manual. Note (Linux): Assert that the user/group that is executing the Tomcat has read access to the WAR file.
Security advice: Please follow the instructions below. Please do not use the default configuration. When using the default configuration, application data and attachments are stored in a folder which is directly accessible via the internet. In certain cases attackers might gain access to the database.
- Create a Communote data directory for storing attachments and application data at a preferred location, for example communote-data. The Tomcat user must have read and write access.
- Create a subdirectory communote in the directory conf of the Tomcat installation.
- Create a file startup.properties in the folder you just created (conf/communote).
- In this file you have to define the absolute path to the data directory of Communote you just created. This is done by adding the following line: communote.data.dir=C\:/Communote/Data Note for Windows: In front of the colon ":" a backslash "\" must be added and all backslashes in the path must be replaced by normal slashes "/". Instead of "C:\Communote\Data" write "C\:/Communote/Data".
Open the file context.xml in the conf directory of theTomcat installation and add the following lines in between the elements <context …> and </context> . Replace the value for communote.config.dir with the absolute path to the startup.properties:
The path must be in the format of your operating system. (Slash in Linux and Backslash in Windows). Escaping characters as in step 4 is not necessary.
- Now you can start your Tomcat and proceed with the installation using the web interface (see section 1.8).
1.6 Further configuration
For a stable Communote, the java system parameteres have to be adjusted. The JAVA_OPTS parameter must be set . The Tomcat has usually a "setenv.bat" / "setenv.sh" available to supplement the parameter
The following parameters are recommended for a typical installation:
Server platforms without graphical user interface
On servers without the graphical interface the parameter -Djava.awt.headless=true has to be set. You can set this parameter within your "setenv.bat" / "setenv.sh":
The parameter -server must not be set on a 32bit platform.
1.7 Update of Communote
For updating Communote it is necessary to update only a part of the installation Prior to the update:
- Stop Communote
- Backup your database and the communote data directory
Update of a Standard Installation Communote generates a directory structure as follows in the installation directory (similar in Windows):
- Get the Communote Update version from our homepage (Communote-Update.zip)
- Delete the content of the directory COMMUNOTE_INSTALL_DIR/communote/communote
- Delete the content of the directory COMMUNOTE_INSTALL_DIR/communote/work
- Extract the zip into the directory COMMUNOTE_INSTALL_DIR/communote/communote On Linux systems make sure that the extracted files have the correct permissions and ownership.
- Start Communote
Hint: When updating a Communote installation of version 2.0 or older to version 2.1 you might need to make some additional configuration. If the file COMMUNOTE_INSTALL_DIR/communote/conf/context.xml does not contain an Environment element with name attribute that has the value communote.config.dir you will have to do the following modifications.
Edit the file COMMUNOTE_INSTALL_DIR/communote/conf/context.xml and add the following entry in between the elements <context> and </context>. The value of the value attribute has to be replaced accordingly.
Create a file named startup.properties in the directory COMMUNOTE_INSTALL_DIR/communote/conf/communote and add the following line. Change the right side of the equals sign to the absolute path of the directory COMMUNOTE_INSTALL_DIR/communote/communote-data
Update of a WAR File Installation
- Stop the Tomcat
- Do a backup (see point 2. „Prior to the update")
- Download the latest WAR File from the Communote Homepage
- In the webapps directory delete the directory ROOT and replace the WAR File named „ROOT.war" in the webapps directory.
- Please check for correct permissions of the WAR file. The user/group under which the Tomcat will be running must have read rights for this file.
- Delete the content of the works directory.
- Restart the Tomcat
Update on Version 2.0
Update to Version 3.1
Communote 3.1 requires a Java Runtime Environment 7 (JRE 7) from Oracle. Please ensure that your installed Java matches this requirement. If not download and install the latest version from http://www.java.com/en/download/
In case you installed your Communote with the help of the installerscript, update the JRE as follows:
- download the new JRE from http://www.java.com/en/download/
- extract the JRE into the directory you have used as the Communote installation-directory during installation. There should already be a directory containing the JRE 6 which is named according to the pattern jre-1.6.x_y
- edit INSTALLATION_DIRECTORY/communote/bin/setenv.sh and change the value of the environment variable JAVA_HOME to the directory of your new JRE 7.
- the old JRE 6 directory can be removed
Support of license expired
Should the support of your license be expired, a message similar to the following will appear. You can do the update but should note that a valid license is required to get all the features of Communote. It is possible to install a valid license after the update.
Figure 1 5: Message
1.8 Final Installation with Web Interface
Start your web browser for the final installation and go to the homepage of your own Communote instance. By default it is accessible on the same host at http://localhost:8080/. Now you should see the start screen of the web installer (Figure 1 6). Follow the single steps. After a successful installation the installer should forward you to the login page of your Communote instance. There, you can log in with your previously specified login data.
Figure 1 8: Installation – Select Database
If you have completed the form, go to the next step of the installation by clicking "Next". In step 4 (Figure 1 9) a connection is made to the database and upon successful connection the database will be initialized. This process may take several minutes. Finally, a success message confirms that the initialization of the database was completed (Figure 1 6). Press Next to proceed with the next step of the installation.
Figure 1 9: Installation – Database Setup
Figure 1 10: Installation – Success Message
In step 5 (Figure 1 11) you define the name of your installation and you select the default time zone. You are able to change those settings in the administration of Communote.
Figure 1 11: Installation – Communote Settings During step 6 you have to provide the credentials for a SMTP-Server (Figure 1 12). This server is used by Communote to send e-mails, for example during the registration process of a new user. You have to specify two e-mail addresses during this step. The first one will be used as sender e-mail address of outgoing e-mails. The second one is optional and will be used as support address. The support address will be linked in the upper right corner of the header in Communote. Using this option you can give your Communote users a possibility for support and help. You can send a test e-mail using the current settings. The e-mail will be sent to the specified sender address.
Figure 1 12: Installation – Mail Settings In step 7 you have to specify an administration account for Communote which will be created during the installation process (see Figure 1 13). You will be able to login in Communote with the-mail or alias and password you specify. Using this account you may create, invite new users or administrate Communote. After completing this step by using the button Finish, the Communote Installer will store the data and prepare Communote for the first usage. This initialization procedure will take a moment, as shown in Figure 1 14.
Figure 1 13: Installation – Admin Account
Figure 1 14: Installation - Finish After the successful initialization a message will be displayed that contains the link to the start page of Communote (Figure 1 15). Use the button Go to Login to get to the Communote start page (Figure 1 16) and log into Communote using the login data you specified in step 7.
Figure 1 15: Installation complete
Figure 1 16: Communote Start Page
1.9 Congratulations to the successful installation of Communote!
In case you have questions or suggestions to the Communote installation or Communote itself, please feel free to contact our customer service by email email@example.com. In case errors occur during the installation, you may try to restart Communote. In the log files of Communote (see chapter 5 of the Administration manual) you may find more detailed information about errors during the installation.
2. Installation and Configuration of Openfire
If you want to use the XMPP integration with Communote you have to install Openfire. At the moment version 3.6.4 is supported.
2.2 Installation of Openfire
Install Openfire using the packet management of your operating system or download it from the Linux version from the Openfire website: http://www.igniterealtime.org/downloads/index.jsp. Download the Windows version from the Openfire website: http://www.igniterealtime.org/downloads/index.jsp. It is recommended to use the installer version for windows.
2.3 Starting the Openfire Installation
- In Linux, start Openfire as follows: Go to the directory <openfire.install.dir> and enter ./openfire start. In Windows you can start or stop Openfire using the start menu.
- Openfire will be started in the background and the administration console will be available under this URL: http://localhost:9090. Go to this URL and follow the installation instructions.
- Choose your language.
- Configure the server settings: Please check the host name.
- Configure the database: Choose "Default database connection".
- Configure the database settings: It is recommended but not necessary to use the same database type as you have chosen for Communote. Before the database can be initialized you have to create it. Execute the following SQL statements on your database, replace openfire_db_name with the database name and communote_db_user_name with the database username:
- For MySQL use: "CREATE DATABASE openfire_db_name CHARACTER SET UTF8;".
- For PostgreSQL use: "CREATE DATABASE openfire_db_name OWNER communote_db_user_name encoding='utf8'".
- Profile Settings: Please use the default settings.
- Administration account: Please enter the login and password for the initial administration account.
- Now you can login with the administration account using the following URL http://localhost:9090. By default the username is "admin" and the password is the one you specified before.
2.4 Configuration of Openfire for Communote
The Communote Installer contains two plug-in for Communote. Please copy those to the following destinations:
- openfire-alias-plugin-VERSION.jar to <openfire.install.dir>/plugins
- openfire-auth-provider-VERSION.jar to <openfire.install.dir>/lib
The plug-in will be found and installed automatically by Openfire after a few seconds. Now follow these steps:
- Open the Openfire administration console (http://localhost:9090) and log in with your administration account
- Change to User -> Groups
- Create a new user
- Choose bot.communote as user name and define a password. Do not assign admin rights to this user.
Proceed as shown in Figure 21:
- Change to User -> Aliases
- Create a new alias: Replace the hostname with the FQDN (Full Qualified Domain Name) of the host Openfire is running on (e.g. server.company.com): Real Jabber Id bot.communote@hostname Alias: * Subdomain: communote
Figure 2 1: Openfire Alias Configuration
Create a file "http-auth.properties" in the following directory: <openfire.install.dir>/conf/. Go to the Communote XMPP configuration by following Administration -> System Administration -> Communication -> XMPP -> Tab Openfire Configuration. Copy the content of the text box into the just created "http-auth.properties" file (see Figure 22).
Figure 2 2: http-auth.properties
Now you have to make the following changes to this property file:
The login of the administrator and the login of the user created before must be defined in the property file. The password must be stored as SHA-1 Hash. With Linux The SHA-1 Hash can be computed as follows: printf 123456 | sha1sum Add the following lines to the http-auth.properties file:
- Check the settings in "url=".
- In the Openfire administration, go to Server -> Server Administration -> System Settings.
- Add a new property (or change it if it already exists): Name: provider.auth.className Value: de.communardo.xmpp.openfire.auth.HTTPRequestAuthProvider.
- Now restart Openfire to activate these changes.
2.5 Configure Communote to use XMPP
- Go to the Communote administration area.
- Go to the menu Communication -> XMPP.
- Set the following values in the tab "Client Configuration" (see Figure 23):
- Server: Enter the host name of the Openfire server. In case the server is running on the same host as Communote you may just enter "localhost".
- Port: Enter the XMPP port Openfire will be running on.
- Login: Enter the login of the bot which you defined during the configuration of Openfire. The default name is bot.communote.
- Password: Enter the password of your bot.
- Check your connection. If this fails please check the configuration in Communote and the configuration of Openfire.
- In the tab "Advanced Settings" enter the following data (see Figure 24):
- Suffix for users (@hostname): Replace "hostname" with the FQDN hostname of the Openfire server, for example: "@server.company.com".
- Suffix for blogs (@subdomain.hostname): Replace "subdomain" with the subdomain of the alias configuration in Openfire. Replace "hostname" with the FQDN hostname of the Openfire server, for example: "@communote.server.company.com".
- Time to wait: The user must wait at least the given amount of time to post another message using XMPP.
- Activate the XMPP service in the tab "Client Configuration". Note: An activated service does not necessarily mean that the communication will work. Therefore please check after activation:
- Is the bot logged-in in Openfire?
- Are you able to establish a connection to the Openfire server using a XMPP client (such as Digsby or Pidgin) with the connection data provided in your user profile?
- Activate the XMPP notifications in your user profile and check if you receive an XMPP notification when a Communote message is posted to you.
- Please check if you are able to post to a blog using XMPP.
Figure 2 3: Page for XMPP -Settings
Figure 2 4: „Advanced Settings" for the XMPP Communication
3.1 Log files
The location of the log files depends on the chosen installation type. In case you installed the Linux package with integration script the Communote logs will be stored in: <communote.data.dir>/log/communote.log. In case you installed the Linux or Windows package without script the Communote logs will be stored in: COMMUNOTE_INSTALL_DIR/communote/logs/communote.log. At the start of Communote a file communote-startup.log will be created. This is located in the bin folder of the executive Tomcats. The location of these log files cannot be changed. During the initialization, Communote is trying to configure logging. For this it needs a log4j.properties file, which must be located in the configuration directory of Communote (chapter "Installing as a WAR" -> communote.config.dir (Step9 )). This file should be created and configured, as otherwise it may happen that important error messages aren't logged . An example of the log4j.properties configuration is shown below. The paths of the log files are configured at the beginning. Usually there is nothing else to adjust but the paths.
3.2 Starting Communote
For WAR file based installations just start and stop the Tomcat as usual. On Linux systems you should be careful to run the commands with the correct user account. For the other installation types do it as follows. With Linux you may start or stop Communote with the following command line statements:
- su PRIVILEGED_USER
Please check after stopping Communote that the process has been stopped as well. Note: the PRIVILEGED_USER is the user that should be allowed to run the application. For installations with the integration script it is the user you selected during script execution. For installations without script it is the user created or selected in the installation step (see section 1.4). With Windows you may start or stop Communote with the following command line statements:
4. Communote Extensions
Communote can be extended with plugins. There is for example a plugin to support integrated Windows authentication based on NTLM when installing and using Communote on Windows (see Single Sign On Plug-in). The installation and deinstallation of such additional plugins is described in this section.
4.1 Installation of a Communote plugin
A Communote plugin is a JAR file which has to be copied to the Communote plugin-directory to get installed. The Communote plugin-directory is usually the subdirectory "plugins" of the Communote data-directory defined during the installation.
A plugin can be installed at runtime. A restart of Communote is normally not necessary and the new features should be available immediately. After installing a plugin which alters the Communote frontend the user has to refresh the page in the browser for the changes to become effective.
After the installation the plugin will be listed in the Communote administration area under "Extensions > Overview".
4.2 Deinstallation of a Communote plugin
To deinstall a plugin the JAR file has just to be removed from the plugin-directory. A restart is usually not necessary.
4.3 Update of a Communote plugin
To update an installed Communote plugin you just have to deinstall it first and install the new JAR file afterwards.