Documentation‎ > ‎

Installation of Corendal DocSide

Prerequirements

Linux or Windows Operating System
Tomcat 5.0 or Tomcat 5.5 (and Java 5.0)
MySQL 5.0 or greater (use UTF-8 as character set)
A running Active Directory domain controller (Windows Server 2003)
A service account

A basic knowledge of Tomcat and MySQL is required to perform this installation. The assistance of your Active Directory administrator might be required as well.

Create and populate the MySQL databases

In this documentation, Windows is assumed with C:\Documents and Settings\Thierry\My Documents\docside being the folder where you extracted the application files. Settings highlighted in orange need to be modified.

Open a MS-DOS command session.

cd C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\installmefirst

mysql -u root -prootpassword

create database docside;
use docside;
source ./sql/main-docside/shared/install/mysql/install_all_shared_mysql.sql;

create database session;
use session;
source ./sql/framework/core/session/install/mysql/install_all_session_mysql.sql;

create database organization;
use organization;
source ./sql/framework/core/organization/install/mysql/install_all_organization_mysql.sql;

create database geography;
use geography;
source ./sql/framework/core/geography/install/mysql/install_all_geography_mysql.sql;

create database proxy;
use proxy;
source ./sql/framework/core/proxy/install/mysql/install_all_proxy_mysql.sql;

create database warning;
use warning;
source ./sql/framework/core/warning/install/mysql/install_all_warning_mysql.sql;

Create the MySQL users

GRANT ALL PRIVILEGES ON *.* TO docs_user@localhost IDENTIFIED BY 'docs_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO docs_user@localhost.localdomain IDENTIFIED BY 'docs_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO session_user@localhost IDENTIFIED BY 'session_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO session_user@localhost.localdomain IDENTIFIED BY 'session_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO orgn_user@localhost IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO orgn_user@localhost.localdomain IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO geog_user@localhost IDENTIFIED BY 'geog_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO geog_user@localhost.localdomain IDENTIFIED BY 'geog_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO proxy_user@localhost IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO proxy_user@localhost.localdomain IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO warning_user@localhost IDENTIFIED BY 'warning_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO warning_user@localhost.localdomain IDENTIFIED BY 'warning_password' WITH GRANT OPTION;

Note: Linux users need to execute these statements twice. First using "localhost" and "localhost.localdomain", then using the host and domain names stored in /etc/hosts. Example using "mylocahost" and "mylocalhost.mylocaldomain":

GRANT ALL PRIVILEGES ON *.* TO docs_user@mylocalhost IDENTIFIED BY 'docs_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO docs_user@mylocalhost.mylocaldomain IDENTIFIED BY 'docs_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO session_user@mylocalhost IDENTIFIED BY 'session_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO session_user@mylocalhost.mylocaldomain IDENTIFIED BY 'session_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO orgn_user@mylocalhost IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO orgn_user@mylocalhost.mylocaldomain IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO geog_user@mylocalhost IDENTIFIED BY 'geog_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO geog_user@mylocalhost.mylocaldomain IDENTIFIED BY 'geog_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO proxy_user@mylocalhost IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO proxy_user@mylocalhost.mylocaldomain IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON *.* TO warning_user@mylocalhost IDENTIFIED BY 'warning_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO warning_user@mylocalhost.mylocaldomain IDENTIFIED BY 'warning_password' WITH GRANT OPTION;

exit;

Customize Active Directory settings

You need to use a service account to connect to Active Directory. If you are just evaluating Corendal DocSide, you can use your own account and password for this evaluation.

in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\datasources\ldapsource\activedocside\ldapsource.xml

    <property name="java.naming.provider.url">ldap://mydomaincontroller.mydomain.mycompany.com:389</property>
    <property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
    <property name="java.naming.security.authentication">simple</property>
    <property name="java.naming.security.principal">myserviceaccount@mydomain.mycompany.com</property>
    <property name="java.naming.security.credentials">myservicepassword</property>
    <property name="com.sun.jndi.ldap.connect.pool">true</property>


in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\datasources\ldapsource\activedocside\nodes\Account.xml

    <dn>dc=mydomain,dc=mycompany,dc=com</dn>
    <preferred-domain>mydomain.mycompany.com</preferred-domain>

in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\datasources\ldapsource\activedocside\nodes\Group.xml

    <dn>dc=mydomain,dc=mycompany,dc=com</dn>

in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\datasources\ldapsource\globalcatalog\ldapsource.xml

    <property name="java.naming.provider.url">ldap://mydomaincontroller.mydomain.mycompany.com:3268</property>
    <property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
    <property name="java.naming.security.authentication">simple</property>
    <property name="java.naming.security.principal">myserviceaccount@mydomain.mycompany.com</property>
    <property name="java.naming.security.credentials">myservicepassword</property>
    <property name="com.sun.jndi.ldap.connect.pool">true</property>


in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\datasources\ldapsource\globalcatalog\nodes\Account.xml

    <dn>dc=mycompany,dc=com</dn>
    <preferred-domain>mydomain.mycompany.com</preferred-domain>

In doubt, ask your Windows administrator for these Active Directory settings.

Customize the applications.xml file

in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\setups

            <property name="framework.core.webapp.protocol">
                http
            </property>
            <property name="framework.core.webapp.host">
                localhost
            </property>
            <property name="framework.core.webapp.port">8080</property>
            <property name="framework.core.webapp.folder">
                /docside
            </property>
            <property name="framework.core.uploads.maxsize">
                50
            </property>
            <property name="framework.core.smtp.host">
                mailserverip.mycompany.com
            </property>
            <property name="framework.core.emails.domain">
                mycompany.com
            </property>
            <property name="framework.core.cookies.domain">
                mycompany.com
            </property>

If you are not using Tomcat, you don't know the port number and you just want to evaluate this application, just remove the framework.core.webapp.port property line. The application will detect automatically the port number. However, this is a required property for production setups.

Customize the jcifs.properties file

This properties file is used by the NTLM authentication. The domain, username and password are required for pre-authentication / SMB sign-in against Windows Server 2003.

in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\properties

jcifs.http.domainController=mydomaincontroller.mycompany.com
jcifs.smb.client.soTimeout=600000
jcifs.netbios.cachePolicy=1200
jcifs.smb.client.domain=mydomain.mycompany.com
jcifs.smb.client.username=myserviceaccount
jcifs.smb.client.password=myservicepassword
jcifs.util.loglevel=1

Customize the C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\setups\applications.xml file to specify which IP ranges should have NTLM authentication.

        <ntlm-ip-address-ranges>
            <ip-address-range>
                <from>127.0.0.1</from>
                <to>127.0.0.1</to>
            </ip-address-range>
            <ip-address-range>
                <from>192.168.0.1</from>
                <to>192.168.0.255</to>
            </ip-address-range>
            <ip-address-range>
                <from>192.168.56.1</from>
                <to>192.168.56.255</to>
            </ip-address-range>
        </ntlm-ip-address-ranges>

To disable NTLM all together, leave only one range, such as:

        <ntlm-ip-address-ranges>
            <ip-address-range>
                <from>128.0.0.1</from>
                <to>128.0.0.1</to>
            </ip-address-range>
        </ntlm-ip-address-ranges>

If you want to use NTLM over HTTPS, there are some tricky setups for your HTTPS proxy because of Internet Explorer bugs. Write me an email for more info: Thierry Danard (tdanard@yahoo.com)

Customize the preprocessor.properties file

This file will be used to perform search/replace in many of the configuration files at startup. Your configuration files will not be changed, this application creates and uses temporary files on startup.

HelpDeskName=My Company's Help Desk
HelpDeskEmailAddress=helpdesk@mycompany.com
HelpDeskPhoneNumber=+1 555 123-4567
HelpDeskApplicationName=DocSide Web Application
PublicApplicationName=DocSide
CompanyName=My Company
ApplicationReleaseDate=April 19th, 2006
UserDocumentationLocation=My Company's User Documentation Home
UserTrainingContact=My Company's User Training Contact
LegalTermsPageURL=My Company's Legal Terms URL


Install the web application

Copy the C:\Documents and Settings\Thierry\My Documents\docside folder to your Tomcat webapps folder (example:C:\Program Files\Apache Software Foundation\Tomcat 5.0\webapps)

Start Tomcat.

Use the application

Depending on your settings, the address of the application should be http://localhost:8080/docside/home/

You will notice that the first page is long to load at first. Each time a page is loaded for the first time, a cache is built.

User accounts

Two users are built-in: demoadmin (password is admin),  and demoguest (password is guest). You can also use your Active Directory account and password.

The application is designed to work with Active Directory. If you want to create your own built-in users, look at the C:\Documents and Settings\Thierry\My Documents\framework\WEB-INF\installmefirst\sql\framework\core\shared\populate\populate_account_table_core.sql for examples. To generate encrypted passwords for these users, use the "main" method of the com.corendal.netapps.framework.core.utils.OneWayEncryptUtil class

Administration

To gain administrator access, just execute a SQL statement. Example if "tdanard" is your Active Directory login :

use docside;
insert into account_role_xref values ('admin1', 'tdanard', 'CORE-ROLE-1', null, null, 'Y');
commit;

To delete the default users:

use docside;
delete from account where id='demoadmin';
delete from account where id='demoguest';
commit;

Once the application is started, you can also use the "System Accounts and Groups Monitor" screens to grant various roles, including Administrator.

MySQL

MySQL has a default limitation of 1 MB for files. You will get a FileTooBigException when trying to upload large files. See www.mysql.com to learn how to change your my.cnf settings. By default, MySQL only indexes words that are at least 4 character-long. This setting can be changed as well.

Install the crons (optional for evaluation)

All cron files for Linux are in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\installmelast\crons.
In Linux, edit your crontab of your "tomcat" user to execute the two crons at system startup (everyminutedocside.cron) and daily (dailydocside.cron)

All bat files for Windows are in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\installmelast\bats.
In Linux, edit your scheduled tasks oto execute the two bats at system startup (everyminutedocside.bat) and daily (dailydocside.bat)


Customization of User Interface

It is fairly easy to adapt the site to your corporate standards.

All template files are in C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\templates. The following files are usually customized to edit the header and the footer of each page:

C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\templates\template-core-page-header.vm
C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\templates\template-core-page-footer.vm

Other files you might want to edit to customize the look and feel of the application are:

C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\setups\styles.xml
C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\setups\colors.xml
C:\Documents and Settings\Thierry\My Documents\docside\WEB-INF\configs\docsidedevconfig\setups\icons.xml
C:\Documents and Settings\Thierry\My Documents\docside\css\screen.css

Oracle

Corendal DocSide has been tested successfully with Oracle 10g .

The Oracle installation is very similar to the MySQL installation, except for the hibernate.cfg.xml files that need to be changed.

Follow this template for hibernate.cfg.xml files.

<hibernate-configuration>
    <session-factory name="java:hibernate/SessionFactory">
        <property name="hibernate.connection.url">
            jdbc:oracle:thin:@(DESCRIPTION =
    (FAILOVER = ON)
    (ADDRESS_LIST =
      (ADDRESS=(PROTOCOL=TCP)(HOST=myhost1.mydomain)(PORT=1521))
      (ADDRESS=(PROTOCOL=TCP)(HOST=myhost2.mydomain)(PORT=1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = DOCSIDE)
      (FAILOVER_MODE =
        (TYPE = SESSION)
        (METHOD = BASIC)
        (RETRIES = 180)
        (DELAY = 5)
      )
    )
  )
        </property>
        <property name="hibernate.connection.driver_class">
            oracle.jdbc.driver.OracleDriver
        </property>
        <property name="hibernate.connection.username">
            docs_user
        </property>
        <property name="hibernate.default_schema">
            docs_user
        </property>
        <property name="hibernate.connection.password">
            docs_password
        </property>
        <property name="hibernate.connection.SetBigStringTryClob">
            true
        </property>
        <property name="hibernate.jdbc.batch_size">0</property>
        <property name="hibernate.jdbc.use_streams_for_binary">
            true
        </property>
        <property name="hibernate.show_sql">false</property>
        <property name="hibernate.statement_cache">0</property>
        <property name="hibernate.transaction.factory_class">
            org.hibernate.transaction.JDBCTransactionFactory
        </property>
        <property name="c3p0.acquire_increment">1</property>
        <property name="c3p0.idle_test_period">100</property>
        <property name="c3p0.max_size">100</property>
        <property name="c3p0.max_statements">0</property>
        <property name="c3p0.min_size">1</property>
        <property name="c3p0.timeout">100</property>
    </session-factory>
</hibernate-configuration>

In this template, an Oracle cluster is used with two nodes: myhost1.mydomain and myhost2.mydomain

The SQL scripts to create the tables and sequences in Oracle are included in this distribution. Instead of  executing source ./sql/main-docside/shared/install/mysql/install_all_shared_mysql.sql, execute @./sql/main-docside/shared/install/oracle/install_all_shared_oracle.sql.

Gotchas

The Velocity templating engine creates a velocity.log file in your tomcat docside at startup. Make sure that you are starting Tomcat under a user that has write-access to that docside.

It's safer to use the Sun JDK rather than the Linux vendor-supplied (.rpm) version.

If Tomcat doesn't start and you used a .war file to deploy this web application, make sure that Tomcat deployed all files.
Comments