Skip to main content

Installing ConSol CM

This section describes how to install the main product ConSol CM.

Please perform the following steps:

Installing the application server​

  1. Extract the downloaded JBoss archive into a new folder.

  2. Edit the file <JBOSS_HOME>\bin\standalone.conf.bat:

    • Change the Java memory options if needed:

      set "JAVA_OPTS=-Xms4g -Xmx4g -Djava.net.preferIPv4Stack=true"

    • Add the Java path (the path and Java version can be different on your system):

      set "JAVA_HOME=C:\Program Files\Java\jdk-11.0.17+8"

      Alternatively you can add JAVA_HOME to your operating system environment variables. In this case it is not necessary to set the line above. Refer to the Java documentation on how to do this.

    • Add DISABLE_JDK_SERIAL_FILTER=true (disable serialization filter) to avoid problems with object (de)serialization (only needed for JBoss EAP > 7.4.12).

warning

The application server should always run under a user without administrator permissions / root access to the operating system.

Installing ConSol CM​

  1. Extract the ConSol CM distribution dist-package-distribution-<CM_VERSION>-wildfly_jboss.zip into JBOSS_HOME.
  2. Overwrite the 4 subfolders bin, domain, modules and standalone, i.e. confirm the overwriting of existing files.

Configuring the database connection​

The database connection is configured in the file cm6-config.properties in the bin directory.

You need to set the following properties:

  • datasource.url: URL of the datasource. Example values:
    • PostgreSQL: jdbc:postgresql://localhost:5432/cmdatabase
    • MySQL 5: jdbc:mysql://localhost/cmdatabase?serverTimezone=Europe/Berlin
    • MySQL 8: jdbc:mysql://localhost/cmdatabase?characterEncoding=UTF-8&serverTimezone=Europe/Berlin
    • Microsoft SQL Server: jdbc:sqlserver://localhost:1433;databaseName=cmdatabase;encrypt=false;trustServerCertificate=true
    • Oracle: jdbc:oracle:thin:@localhost:1521/SERVICE_NAME
  • datasource.username: Name of the database user for ConSol CM
  • datasource.password: Password of the database user for ConSol CM

If you use ConSol CM with CMRF, uncomment the lines with the CMRF datasource and set the required values.

Standalone authentication application

If you use the standalone version of the authentication application (cm-auth-user-standalone.jar), you need to provide the database connection in the cmas-auth-user.properties file.

Adding the database driver (MySQL only)​

MySQL Connector/J is the official JDBC driver for MySQL. The connector is not part of the ConSol CM distribution package. Therefore, you must copy it manually into the application server directory.

  1. Download the connector from http://dev.mysql.com/downloads/connector/j/ (select the platform-independent download). You need version 8.0.22.
  2. Extract the MySQL connector file mysql-connector-java-8.0.22.zip into a temporary folder. The folder contains the JDBC driver file mysql-connector-java-8.0.22-bin.jar.
  3. Copy the JDBC driver, e.g. mysql-connector-java-8.0.22-bin.jar, into the folder <JBOSS_HOME>\modules\system\layers\base\com\mysql\jdbc\main.
  4. Edit the file <JBOSS_HOME>\modules\system\layers\base\com\mysql\jdbc\main\module.xml located in the same folder. Change the line highlighted in red, so it points to your version of the MySQL connector.
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql.jdbc">
  <resources>
    <resource-root path="mysql-connector-java-8.0.22-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

Enabling traffic encryption (Microsoft SQL Server only)​

The exchange of credentials is encrypted by default. In addition, the complete traffic can be encrypted by setting encrypt=true in the JDBC connection string. We recommend to switch on encryption on production systems after a thorough testing phase only.

Starting and stopping ConSol CM​

This section describes the basic start and stop commands of the application server. They can be executed on the command line. For production environments, you usually integrate these commands into an environment which allows automatic system start and stop. You might want to write an init.d or systemd script for a Linux system, or configure ConSol CM as a service on a Windows system.

info

If you have a maintenance contract, please contact the ConSol CM support to receive further assistance with the configuration.

Starting ConSol CM​

Run the following command to start the application server. Replace cm6-<DB>.xml with the configuration file for your database:

  • PostgreSQL: cm6-postgresql.xml
  • MySQL 5: cm6-mysql-5.xml
  • MySQL 8: cm6-mysql-8.xml
  • Microsoft SQL Server: cm6-mssql.xml
  • Oracle: cm6-oracle.xml
<JBOSS_HOME>\bin\standalone.bat -P <JBOSS_HOME>\bin\cm6-config.properties -c cm6-{DB}.xml
warning

If the database has to be restarted, stop the application server first, wait until the database is available again, and then start the application server.

Stopping ConSol CM​

Run the following command to stop the application server.

<JBOSS_HOME>\bin\jboss-cli.bat --controller=localhost:9999 --connect --command=:shutdown

If you did not set a system environment variable for the Java home directory, add the path to the JDK to <JBOSS_HOME>\bin\jboss-cli.bat. This prevents Java warnings.

Example for JDK version 11.0.17, replace by your Java version.

set "JAVA_HOME=C:\Program Files\Java\jdk-11.0.17+8"

In case the JBOSS_HOME environment variable is already set in the system, you can specify the server-specific path at the beginning of <JBOSS_HOME>\bin\jboss-cli.bat in the following syntax:

set JBOSS_HOME=<YOUR_JBOSS_HOME>

General settings​

  • If -b=localhost or -b=127.0.0.1 is set as parameter, ConSol CM is only accessible from the same server where the application server runs.
  • Enter the network IP or the network name to make ConSol CM accessible from outside the sever. In this case, the ConSol CM URL is not accessible from the inside using the localhost URL.
  • If you enter -b=0.0.0.0 the server is accessible from the outside and inside using the server URL or using the localhost URL. You need to take care of all required security-related precautions.

Setting up ConSol CM​

This section describes how to set up ConSol CM. This step is needed to create the database structure and configure some basic aspects of the application. You need to make the settings in several tabs.

  1. Open the ConSol CM URL in a web browser. The default URL is http://localhost:8080.
  2. General tab:
    • Data directory: Choose a folder for application-relevant files. The following subfolders will be created automatically:
      • index for the index, with a subfolder for each index
      • mail for failed incoming emails which cannot be saved to the database
  3. Database tab:
    • Recreate tables: When using the setup dialog during a reinstallation of ConSol CM, you can select this checkbox to rebuild the database scheme. This deletes all data. For a new installation, you do not need to select this checkbox.
  4. Administrator tab:

    • Login: The username of the administrator account (for the Web Admin Suite)

    • Password: The password of this administrator account.

    • Confirm password: Confirm the password for the administrator account.

    • Email: The email address for the administrator, which should be used for system notifications (system property cmas-core-security, admin.email). For some modules, separate email addresses can be configured, see section Email configuration in the ConSol CM Administrator Manual.

      tip

      You can change this email address later using the Web Admin Suite.

    info

    It is recommended to create personalized users and grant them administrator permissions instead of using a generic administrator account. Please remove the administrator account created during the setup before using the system in production environments. Be aware that this administrator account always uses database authentication even if LDAP or SSO is used for the rest of the user accounts.

  5. Scene tab:
    • Scene: Decide if you want to set up the system with a pre-defined environment or if you would like to start with an empty system and import a scene later, see ConSol CM Administrator Manual, section Staging.
      • No scene: Select this value if you would like to start with an empty system. You can import a scene later using the Web Admin Suite.
      • Ticketing Scene: This installs the ConSol CM/Ticketing product.
  6. Outgoing E-mail tab:

    • Outgoing E-mail connection (optional): Enter the URL of the SMTP server which should be used for sending emails. If you leave the outgoing email connection empty, you can set it later in the Web Admin Suite, see ConSol CM Administrator Manual, section Email configuration.

      warning

      Email passwords containing special characters might not work during the setup of ConSol CM. Please use the Web Admin Suite to set such passwords.

  7. Incoming E-mail tab:

    • Incoming E-mail connection (optional): Define an email account (mailbox) where ConSol CM should retrieve incoming emails. If you leave the incoming email connection empty, you can set it later in the Web Admin Suite, see ConSol CM Administrator Manual, section Email configuration.

      warning

      Email passwords containing special characters might not work during the setup of ConSol CM. Please use the Web Admin Suite to set such passwords.

  8. Click the Finish button to start the setup. This will take a while (some browsers might display a timeout error, but this does not indicate any problem). When the setup has finished you see a screen with the message Setup has finished.
  9. Reload the page to see the start page with links to the Web Client and Web Admin Suite. Open the Web Admin Suite and go to the License page to add your license, see License