#
# VKC Virtual Knowlegde Center
# Created and developed by C-LAB (Cooperative Computing & Communication Laboratory)
# Fuerstenallee 11 / 33106 Paderborn / Germany
#

#
# C-LAB: The public private partnership of "Siemens IT Solutions & Services" (SIS) and "University of Paderborn" (UniPB) 
# www.c-lab.de
# 

#
# Date of OpenSoure release: 2011-06-28
# Release Version: 5.1.0
#

#
# License: 
# This software is released under EUPL 1.1 model (European Union Public License) 
# For further information take a look @
# - http://www.osor.eu/eupl
# - http://en.wikipedia.org/wiki/European_Union_Public_Licence
#

#
# VKC "R" us: 
# It is highly appreciated to give some 
# feedbacks, comments or ideas for improvement !!!
# Just drop an email to "marketing@c-lab.de"
# We "R" listening !
#


V K C
 __   __   __     ______     ______   __  __     ______     __           
/\ \ / /  /\ \   /\  == \   /\__  _\ /\ \/\ \   /\  __ \   /\ \          
\ \ \'/   \ \ \  \ \  __<   \/_/\ \/ \ \ \_\ \  \ \  __ \  \ \ \____     
 \ \__|    \ \_\  \ \_\ \_\    \ \_\  \ \_____\  \ \_\ \_\  \ \_____\    
  \/_/      \/_/   \/_/ /_/     \/_/   \/_____/   \/_/\/_/   \/_____/    
 __  __     __   __     ______     __     __     __         ______     _____     ______     ______    
/\ \/ /    /\ "-.\ \   /\  __ \   /\ \  _ \ \   /\ \       /\  ___\   /\  __-.  /\  ___\   /\  ___\   
\ \  _"-.  \ \ \-.  \  \ \ \/\ \  \ \ \/ ".\ \  \ \ \____  \ \  __\   \ \ \/\ \ \ \ \__ \  \ \  __\   
 \ \_\ \_\  \ \_\\"\_\  \ \_____\  \ \__/".~\_\  \ \_____\  \ \_____\  \ \____-  \ \_____\  \ \_____\ 
  \/_/\/_/   \/_/ \/_/   \/_____/   \/_/   \/_/   \/_____/   \/_____/   \/____/   \/_____/   \/_____/ 
 ______     ______     __   __     ______   ______     ______          
/\  ___\   /\  ___\   /\ "-.\ \   /\__  _\ /\  ___\   /\  == \         
\ \ \____  \ \  __\   \ \ \-.  \  \/_/\ \/ \ \  __\   \ \  __<         
 \ \_____\  \ \_____\  \ \_\\"\_\    \ \_\  \ \_____\  \ \_\ \_\       
  \/_____/   \/_____/   \/_/ \/_/     \/_/   \/_____/   \/_/ /_/  
     
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMMMMMO7MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMMMM78D?MMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMMMMO8DONMMMMMMMMMNNMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMMM7D8DDZMMMMMMMM==~==MMMMMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMM?D88DDDMMMMMMM=~====~~~MMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMM8888DDD?MMMMM=~~=~~~~~~==~7MMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMM?D8888DDOMMMMM=++=~~~====~=~+MMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMM888888DDD$MMM=~~===~~~??=~~=~==7MMMMNN
MMMMMMMMMMMMMMMMMMMMMZD88888DDDN7M~~~=+=~~~==~~~==~~OO7MMMNN
MMMMMMMM++??I?+MMMMM7D88888DDDDDN??=~~~+?I==+=~=~:+OOZMMMMNN
MMMMMM++===++?II?MMMOD88888DDDDDDI==~~~=?=~+~~~=~~$OO+MMMMNN
MMM==~::::::~==++?I?8888888DDDDDDD$=~~~~~?+~~~~=+IOZ+MMMMMNN
MM+~::,,,,,:::~~~~~I8888888DDDDDDDNI=~~~~+++?=+=+OO?MMMMMMNN
M+~:,,,...,,:,,,,,,O8888888DDDDDDDD8~~====+~~?+=ZODMMMMMMMNN
==::,,,...,,,,....,$888888D8DDDDOO$?++??+~=+=~=?OZMMMMMMMMNN
+=~:,,,,,,,,........:~MMMMMMMMMMMMMMMM=====~++7OOOMMMMMMMMNN
?+~:::,,,:,.........,:MMMMMMMMMMMMMMMMMM+?7777$$7MMMMMMMMMNN
??=~~:::::,.........,:MMMMMMMMMMMMMMMMM$I7777$$$$OMMMMMMMMNN
I$++=~~~~:,,........,~MMMMMMMMM=?777ZM+I7$$ZOZ7$$$MMMMMMMMNN
M?$7?++++~::,,....,,?II?+I$$Z7+?77$Z+??$$O77OO$?7ZMMMMMMMMNN
MMMZ$77I?=~:::,:::,?777O~I77$7777ZZ+++I7ZIMMMM$DDOMMMMMMMMNN
MMMMZ$Z$I?77+~=~~~~?77ZZ~I77ZI7$Z$?M?=7$OMMMMMM$INDMMMMMMMNN
MMMMMMMI+777ZI==M==77$OI~777777Z7MMMI~77OMMMMMM+I$$MMMMMMMNN
MMMMMMM??I77$ZMMM+I77O+I~777$7Z?MMMMI:77Z?MMMM?+7$OMMMMMMMNN
MMMMMMMM7?777ZIM=?77O?MI~77777$7+MMMI=+$$O+MM+?7$$$MMMMMMMNN
MMMMMMMM$+777$$M=I77OMMI=7777777$?MM7I=$$$$II77$$Z+MMMMMMMNN
MMMMMMMMI=7777O++77$=MMI:7$7$77$7$77$Z77$$$$7$$$OZMMMMMMMMNN
MMMMMMMMM??777$?77$$MMMI:777Z87777$$$O$OZ$ZZO8DZ?MMMMMMMMMNN
MMMMMMMMMI=7777777OZMMM7:$77O$ND8O88ZMMZO8O7IMMMMMMMMMMMMMNN
MMMMMMMMMO+I7777$$ZIMMM7:$77Z$ZDNNDO+MMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMZ7=77777Z?MMMM$77Z87MMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMM$+I777O=MMMMM?8DZ+MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMI$OO88INMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMMODDOIMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNN

***     
     
     /|
     .-((--.
    ( '`^'; )
    `;#    |    How to setup VKC 5.1.0
     \#    |
      \#   \                
       '-.  )
          \(
           `

This document describes in brief how to setup a VKC system step by step

Note: "<...>" denotes variable content (to be defined by customer)

*********************************************************************************************
***                                                                                       *** 
***   S T E P S                                                                           ***
***                                                                                       ***
*********************************************************************************************

1. Setup a TOMCAT application server (tomcat.apache.org)

2. Setup a Database Management System (Oracle/Firebird/Postgres)

3. Setup an Eclipse IDE and load VKC5 as new project
   or install build tool "ANT" (ant.apache.org)

4. Setup following directories:
    The directories are used by the vkc system and need to be setup up physically on the operating system and 
    referenced in the database setup script (see 5.)   
   
	- classifyindex : directory for the indices for classification <classifyindex dir>
	- searchindex   : directory for the indices for the searchengine <searchindex dir>
	- datastorage   : directory for datastorage (where uploaded files a placed) <datastorage dir>
	
5. Change in "VKC5/db/dbschema/scripts/{interbase | oracle | postgres}/*_setup.sql" values concerning following systempaths:  

    # datastore directory
    values (1054, 'SYSTEMPATHS', 'sysparam.context.systempaths', 'DatastoreDir', 'sysparam.context.systempaths.datastoredir', '<datastoreDir>', '', 'sysparam.context.systempaths.datastoredir.descr', 9050, 0, 0, 0, 0)
    
    # searchindex directory
    values (1055, 'SYSTEMPATHS', 'sysparam.context.systempaths', 'SearchIndexDir', 'sysparam.context.systempaths.searchindexdir', '<searchIndexDir>', '', 'sysparam.context.systempaths.searchindexdir.descr', 9100, 0, 0, 0, 0)
    
    # classifyindex directory
    values (1056, 'SYSTEMPATHS', 'sysparam.context.systempaths', 'ClassifyIndexDir', 'sysparam.context.systempaths.classifyindexdir', '<classifyIndexDir>', '', 'sysparam.context.systempaths.classifyindexdir.descr', 9150, 0, 0, 0, 0)

    # root url of vkc system
    values (1033, 'MAIL', 'sysparam.context.mail', 'RootURL', 'sysparam.context.mail.rooturl', '<root url, e.g.:http://localhost:8080>', 'URL of ', 'sysparam.context.mail.rooturl.descr', 7250, 0, 0, 0, 0)

    # admin email 
    values (1034, 'MAIL', 'sysparam.context.mail', 'AdminEmail', 'sysparam.context.mail.adminemail', '<adminEmailAddrs, e.g. admin@company.com>', 'EMail adress of the administrator', 'sysparam.context.mail.adminemail.descr', 7300, 0, 0, 0, 0)

    # mail server address
    values (1035, 'MAIL', 'sysparam.context.mail', 'MailServer', 'sysparam.context.mail.mailserver', '<mailServerAddr, e.g. mail.company.com>', 'Mailservers adress', 'sysparam.context.mail.mailserver.descr', 7350, 0, 0, 0, 0)

6. Connect to database management system and run following script in a sql console to setup VKC db:
	(e.g. a nice console tool is "ibconsole.exe" (can b found elsewhere in the net) 
	      or "aqua data studio" (java-based) 
	      or via eclipse database plug-ins
	      or ...
	
	firebird : "VKC5/db/dbschema/scripts/interbase/vkc_db_interbase_setup.sql"
	oracle   : "VKC5/db/dbschema/scripts/oracle/vkc_db_oracle_setup_10g.sql" (for oracle 10g)
 	postgres : "VKC5/db/dbschema/scripts/postgres/vkc_db_postgres_setup.sql"
 
7. Modify "VKC5/defaultroot/WEB-INF/vkc.properties"

    !!! take a look @ "vkc.properties.tmpl" (it's a template-file)  !!!
    !!! copy "vkc.properties.tmpl" 2 "vkc.properties"               !!!
    !!! modify "vkc.properties" 2 your needs                        !!!
	
    # vkc server properties (for communication with converter server)
    vkc.server.id       = <id>    // numerical id of the vkc server
    vkc.server.port     = <port>  // port number
    vkc.server.hostname = <qualified domain name> (e.g. abc.company.com)
	
    # vkc db properties
    vkc.db.driver_class = <package name of java db driver) 
	                   (e.g. firebird: org.firebirdsql.jdbc.FBDriver)
                           (e.g. oracle: oracle.jdbc.driver.OracleDriver)
	
    vkc.db.url          = <jdbc-db-url> 
	                   (e.g. firebird: jdbc:firebirdsql:abc.company.com/3050:c:/VKC.GDB)
                           (e.g. oracle: jdbc\:oracle\:thin\:@abc.company.com\:1521:\<servicename>	                                           
	
    vkc.db.username     = <username for db>
    vkc.db.password     = <password for db>
 
8. Modify converter properties file "VKC5/converter-dist/converter.properties"
	
    !!! take a look @ "converter.properties.tmpl" (it's a template-file) !!!
    !!! copy "converter.properties.tmpl" 2 "converter.properties"        !!!
    !!! modify "converter.properties" 2 your needs                       !!!
	
    vkc.converter.id            = <id>    // numerical id of the converter server
    vkc.converter.port		= <port>  // port number
    vkc.converter.hostname	= <hostName> // <qualified domain name> (e.g. converter.company.com)

    # Converter specific properties (local referenced)
    vkc.converter.verbose	= true
    vkc.converter.cpath		= <converterDir>/bin/win32
    vkc.converter.office	= MsOffice 
    vkc.converter.office	= OpenOffice

    vkc.converter.ooserver	= <hostname of openOffice server>
    vkc.converter.quickstart= <path to openOffice quickstart>/quickstart.exe
        
    vkc.converter.logdir	= <converter server logDirPath>

    # Database specific properties
    vkc.db.username       = <username for db>
    vkc.db.password       = <password for db>
    
    vkc.db.driver_class   = <package name of java db driver) 
                            (e.g. firebird: org.firebirdsql.jdbc.FBDriver)
                            (e.g. oracle: oracle.jdbc.driver.OracleDriver) 
    
    vkc.db.url            = <jdbc-db-url> 
	                    (e.g. firebird: jdbc:firebirdsql:abc.company.com/3050:c:/VKC.GDB)
                            (e.g. orcle: jdbc\:oracle\:thin\:@abc.company.com\:1521:\<servericename>	
    
    vkc.db.pool_size      = 2

    # used by the Java Service Launcher
    vkc.converter.stopport    = 8465
    vkc.converter.servicename = <ConverterService-ServiceName>


9. Build VKC5 Web Application aRchive "VKC5.WAR":

    - Eclipse IDE:    
       - rightclick on "VKC5/build.xml"
       - "Run as...| Ant Build..."
       - Choose targets "init", "compile_classes", "generate_war"
       - Click "run"
       ==> the result is "VKC5/distrib/vkc5.war"
	   
    - ANT Build Tool :
        - step into <VKC5-dir> (where the build.xml file resides)
        - run "ant init, compile_classes, generate_war"
 
10. Build converter server
    
    - Eclipse IDE:
       - rightclick on "VKC5/build.xml"
       - "Run as...| Ant Build..." 
       - Choose targets "init", "compile_classes", "create.vkc5_jar", "dist.converter"
       ==> the result is in "VKC5/converter-dist"
     
     - ANT Build Tool:
       - step into <VKC5-dir> (where the build.xml file resides)
       - run "ant init, compile_classes, create.vkc5_jar, dist.converter"
     
11. Deploy "VKC5/distrib/VKC5.WAR" in "<%TOMCAT_HOME%>/webapps"
    
    If the application should run outside of "<%TOMCAT_HOME%>/webapps" u have
    to adjust the path <%TOMCAT_HOME%>/conf/server.xml similar like this:
     
    <Context path="VKC5" reloadable="false" docBase="D:\vkcext\webapp\">
    ...

12. Copy "VKC5/converter-dist" to a <converterDir> (as defined in 8.)
    	
13. Start tomcat webserver 

14. Start converter (or install as service)
	- step into <converterDir>
	- standalone: "runConverter.bat" (windows), "runConverter.sh" (unix)
	
        - Install/Uninstall as Windows Service: 
           -  Install  : runConverterAsService (windowsXP), installConverterServiceWithWinserv.bat (win7)
           - Uninstall: uninstallConverterAsService (windowsXP), uninstallConverterServiceWithWinserv.bat (win7)
      
         - Start as Windows Service
           - Step into "Services" dialog in "SystemControl" and start <VKCConverterServer-serviceName> 
             (as defined in "installConverterServiceWithWinserv.bat" or "vkc.converter.servicename" in "converter.properties"  

15. Start browser and type in vkc system root url (see 5.): e.g. "http://localhost:8080" 
  
15a. To compile all JSPs ahead before 1st call try following command: 
     - delete dir "<%TOMCAT_HOME%>\work\*>"
     - type url in browser: "<root-url>/commons/compileJSPs.jsp" 
     ==> all jsp's should be compiled without error
     
     ***!!! IMPORTANT !!!***
     if ( tomcatVersion >= 5.5.27) then following option MUST be set:
        <%TOMCAT_HOME%>/conf/catalina.properties: org.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING = false
     
     otherwise four jsp's will not compile correctly !
     
16. Security
    To run VKC application via secure SSL(https) adjust the settings in  
    "<%TOMCAT_HOME%>/conf/server.xml" 
    and 
    "<VKC5-dir>/WEB-INF/web.xml"
    
    4 further information refer to appropriate documentation of the used tomcat server ! 
     
17. Be happy & keep it real ;-)


*********************************************************************************************
***                                                                                       *** 
***   N O T E S                                                                           ***
***                                                                                       ***
*********************************************************************************************

1. Main Administrator (VKC SuperUser): 

   Initially the SuperUser of VKC system is named "Admin". 

   Main Administrator account name   : "Admin"
   Main Administrator account passwd : "AdminPwd"
   
   U r free to assign an administrator privilege to a given user or create new users with administrator privileges:
   - AdministrationView | Users
   - click on an individual account or create a new user
   - check AdministratorPrivileges box
   
   The "Admin" user or a user with administrator privileges has full control of the VKC system !

2. To change text for the user interface modify following file:
     User's locale (operating system attribute) is consulted to determine the languageCode (de, ru, en, ...)
     
     - VKC5/src/resources/application.properties (default english(en), if locale could'nt be determined)
       or 
       VKC5/src/resources/application_<languageCode>.properties

3. To add a new language for the user interface of VKC following steps are required:
     User's locale (operating system attribute) is consulted to determine the languageCode (de, ru, en, ...)
     
     1. Create an new language file in "VKC5/src/resources/application_<languageCode>.properties"
     2. Change the values of the keys 2 your needs
     3. Log into DatabaseManagementSystem, connect to VKC database and add a new record 2 table "languages"
     
        languageId      : numerical ID as consecutive number
        name            : name of the language (used only internally)
        name_key        : key name of the language in "application_<languageCode>.properties" (e.g. "vkc.language.<someLanguage...>")
                          2 b displayed in VKC dialogs (e.g. in UserProfile dialog to define a user's preferred dialog language)
        short_name      : <languageCode>
        isocode         : not longer valid & obsolete: Everything 2 display within VKC will be handled with "UTF-8" character encoding  
        defaultlanguage : 1 = default language for VKC, 
                          0 = not the default language 
                          (!!! NOTE: there must be just only one default language entry !!!) 
     4. Add key name of language to "application_<languageCode>.properties"
        (e.g.: vkc.language.<someLanguage> = someLanguageName) 
      
4. Many of the configuration parameters could be adjusted in following VKC dialog:
     AdministrationView | Configuration

5. Due to some problems please use "/" instead of "\" for the description of paths inside VKC
   AdminstrationView | Configuration | Logging:
   InfoFile, ErrorFile, TraceFile, MigrationFile, AccessFile, WebDAVFile

   e.g. instead of InfoFile path 
   "d:\vkcext\data\log\vkc_info.log"
   describe it like this:
   "d:/vkcext/data/log/vkc_info.log"
         
6. A documentation for the VKC system is available under the tab "Help" (in german) 
   or type or use follwing url: "http://<vkcServerUrl>/helpView.do?viewId=0  

7. Change barebone look and feel for VKC
   
   - html code resides in jsp-files:
     VKC5/defaultroot/templates/default/*.jsp
   
   - employed grafix (icons et al.) reside in
     VKC5/defaultroot/templates/default/gfx     
   
   - main css:
     VKC5/defaultroot/templates/vkc.css
     
          
                         )/_
               _.--..---"-,--c_
          \L..'           ._O__)_
  ,-.     _.+  _  \..--( /           j|>
      `\.-''__.-' \ (     \_         y|      
      `'''       `\__   /\
                  ')

     