ESS Installation Information
(Obsolete - Use Manual Installation Procedures Version 7)
Copyright 2005, 2006, R. James Holton. All rights reserved.
Installers
There are 4 automatic installers. They are:
ESA-3.(n).(n)w-windows-installer.exe: The Appliance Edition installer creates a complete ESS environment on Windows NT, 2000 and XP. This includes installing Apache, Mod_jk2, Tomcat and MySQL (optional) applications in a sandbox environment. Items in the sandbox do not negatively impact other versions of these applications.
ESA-3.(n).(n)l-linux-installer.bin: The Appliance Edition installer creates a complete ESS environment on a Linux box. This includes installing Apache, Mod_jk2, Tomcat and MySQL (optional) applications in a sandbox environment. Items in the sandbox do not negatively impact other versions of these applications.
ESS-3.(n).(n)-windows-installer.exe: Adds the ESS application to an existing application server and database on Windows NT, 2000 and XP.
ESS-3.(n).(n)-linux-installer.bin: Adds the ESS application to an existing application server and database on Linux.
Information
Required for Installation (Appliance Edition/ESA Installers)
The following information is required to install the Appliance Edition/ESA. You should gather this information prior to running the installation program. The configuration file that stores the information is indicated in parenthesis after the description.
1. E-mail domain name: This is the domain that is used by your e-mail system. It is generally a name followed by either a ".com", ".org" or similar ending. For example, Adisoft's domain is adisoft-inc.com. (system.xml)
2. Expense email user address: Enter the email address that ESS will use to send out email messages to users. ESS uses email as part of its workflow. This must be an active email address.
3. SMTP server name: ESS uses an SMTP server to send e-mail messages. ESS defaults the port to 25 as the standard SMTP port number. Examples of valid syntax are: adisoft-inc.com, mail.myserver.com, or smtp.company.com. (system.xml)
4. Web server domain: This is the domain of the expense server. Examples are: www.myserver.com and dedicated_expense_server.org.
5. Database password: Enter the password for the database user. (web.xml)
The installer also checks for default ports and if the ports are occupied will ask for the following information. If you enter a port that is already assigned, the installer will prompt you to try another value.
6.
7.
8. Tomcat JK Listener Port: The normal Tomcat shutdown port is 8009. If not available, you can try "18009".
9.
During the installation, you'll be prompted for an installation directory. We suggest that you leave the default value as is. You should copy down the location of the installation directory, as you'll need it to launch ESS via the essctl script.
Information
Required for Installation (ESS Installers)
The following information is required to install ESS on existing Web, application and database servers. You should gather this information prior to running the installation program. The configuration file that stores the information is indicated in parenthesis after the description.
1. Location of the application server's webapps folder: This is the place that holds your Web application (i.e., JSP and Java classes). It will normally be the location of your "webapps" folder. Use the open folder/file manager icon to search for it. (system.xml)
2. Location of your web server's html folder: This is where your html is stored. Use the open folder icon/file manager to search for it. It is normally called either "htdocs" or "html". (system.xml)
3. E-mail domain: This is the domain that is used by your e-mail system. It is generally a name followed by either a ".com", ".org" or similar ending. The stock profiles, admin, reporter, approver, and auditor will use this domain. For example, Adisoft's domain is adisoft-inc.com. And also, admin will be assigned the email address of admin@mycompany.com if you enter mycompany.com as the email domain. You may want to set up email accounts for the stock users for test purposes. (system.xml)
4. Database that you use: This is either MySQL, MS SQL Server or Oracle. If you use a different database, you'll need to modify the system.xml, and the URLs provided to generate javascript profiles and reset passwords.
5. Database server connection string: If the database server is not on the same machine as the application server (e.g., Tomcat), you need to know the server name and port address of the database server. Consult with your database administrator.
6. Expense email user address: Enter the email address that ESS will use to send out email messages to users. ESS uses email as part of its workflow. This must be an active email address.
7. SMTP server name: ESS uses an SMTP server to send e-mail messages. ESS defaults the port to 25 as the standard SMTP port number. Examples of valid syntax are: adisoft-inc.com, mail.myserver.com, or smtp.company.com. (system.xml)
8. Web server URL: This is the full URL of the expense server's Web server. Examples are: http://www.myserver.com, https://expenses.mycompany.com, and https://dedicated_expense_server.org. Be sure to include the "http:" or "https:". (system.xml)
9. App server URL: This is the full URL of the expense server's application server. Examples are: http://www.myserver.com, https://expenses.mycompany.com, and http://dedicated_expense_server.org:8080. Be sure to inclued the "http:" or "https:". Avoid using a port number, such as "8080", if you are using the "https:" protocol or want to support Mozzila-based browsers, unless you are installing an application server only system. Use of a conduit between the Web server and application server, such as mod-jk, eliminates the need for the port designation. (system.xml)
10. Database user: Enter the MySQL user name that has access to the "adisoft" database that you will create. This can be the "root" login for dedicated systems. (web.xml)
11. Database password: Enter the password for the database user. (web.xml)
During the installation, you'll be prompted for two additional pieces of information: Installation Directory, and Location of scripts and xml database. With the exception of the drive used for the "Location of the scripts and xml database", we suggest that you leave the default values.
Installing ESS with
an Installer
If you are using the Appliance Edition/ESA, run the ESA-3.n.n-linux-installer.bin for Linux and ESA-3.n.n-windows-installer.exe for Windows. After running the installers, skip to in "Launching ESS" below.
The remaining instructions in this section are for
installing ESS with the ESS Installer with the MySQL, MS SQL Server or Oracle
databases. If you are using a different
database, you should consult the support section of Adisoft's Web site
(www.adisoft-inc.com). You'll need to
register for this service. As of
1. Make sure that you have your Web and application servers installed. If you are using a Web server and applicaton server combination, you'll probably also want to have a conduit, such as connector-j, installed. This will allow you to use https (ssl) to protect your browser sessions. It also resolves cross-frame addressing in Mozilla-based browsers. Additionally, there are several companies that provide LAMP stacks for easy installation of Apache and Tomcat servers, as well as the MySQL database. Two Web sites to check for LAMP stacks are www.bitrock.com and www.spikesource.com.
2. Stop the Web and app servers and/or associated services/daemons.
3. Run the ESS-3.n.n-windows-installer.exe for Windows installations (ESS-3.n.n-linux-installer.bin for Linux). Be sure to pay attention to the description. Please consult the section above for a description of the information that is required by the installation process. If installing on a system that has only an app server and no Web server, you should install the ess folder (HTML and JavaScript) under ess-app.
4. Installing the database. You'll need to install your database server. After installation, use the provided scripts to set up an 'adisoft' database. These scripts are located in the ess/dbconfig folder under a sub folder with the database name (mysql, sqlserver, oracle). Log into your database (MySQL, MS SQL Server, or Oracle) and create an 'adisoft' database. Then execute the MASTER.SQL script. There may be other scripts in the dbconfig database subfolder, but you don't need to execute them. The MASTER.SQL script will create all the tables that you need. (
5. If you are using a proprietary database, such as MS SQL Server or Oracle, you'll need to install the JDBC drivers into the tomcat/webapps/ess-app/WEB-INF/lib folder. If you are using MySQL, the driver is part of the installation process and you don't have to do anything. If you need to install the JDBC drivers, see below.
6. Review the '/ess/var' (or 'c:\ess') folders. Make sure that the user that starts your application server (e.g., Tomcat) has all access to these folders. Also make sure this user has full access to the ESSProfile.js and AuditProfile.js files found in the 'ess' folder under your Web server.
7. Restart your application and Web server. If you have a conduit or connector, such as connect-j, test the conduit separately before continueing. You may need to reset the computer.
8. Your should be able to access both the Reporter and Auditor modules now. The links are in the Expense Submittal System menu. The default ESS administrator is admin (e.g., admin@yourcomapny.com). The password is 'adisoft'. Use this profile to access the modules. There are three other profiles available. You can view them in the Audit module and activate them for testing. There are other users already in the database (report, approver, and auditor). You can search on their personnel number by entering a '0' in the field at the bottom of the 'User - Primary information' screen in the Audit module.
Launching ESS
(Appliance Edition/ESA)
If you have installed with the ESS installer (non-Appliance Edition), ESS is launched as part of your Web and application servers. Normally these are run in the background. If you install ESS with the Appliance Edition/ESA installer, on Linux, you need to run the essctl.sh script. This can be chronned. To start ESS, from the ESS-3.n.n folder, type:
./essctl start
The essctl.sh script contains other options, such as stopping ESS,. or starting and stopping one of the associated services. For more information on essctl.sh functionality type:
./essctl help
JDBC
Database Drivers, etc.
ESS uses JDBC to connection to your database. The drivers mentioned here are all jar files that contain Java class files.
If you use MySQL, you're set. The MySQL JDBC drivers ship with ESS and will automatically be installed in the webapps/WEB-INF/lib folder.
If you are using Microsoft SQL Server, you need to download the drivers from the Microsofts Web site. There is an installation program that gets run. After you download the drivers you need to move them to the
webapps/WEB-INF/lib folder. The files you need to copy are msbase.jar, mssqlserver.jar and msutil.jar.
If you are using Oracle, you need to copy the JDBC drivers into the webapps/WEB-INF/lib folder. Drivers for Java 1.4 are nls_charset12.jar and ojdbc14.jar. The drivers for Java 1.3 are classes12.jar and mls_charset12.jar. You may be able to find these drivers in your oracle/ora92/jdbc/lib folder.
Another note regarding the Oracle dirvers: The Installer will give you, as a default, the following string:
jdbc:oracle:thin@localhost:1521:adisoft
An explanation for each item is:
jdbc:oracle:thin - driver being used.
localhost - address of the machine hosting the Oracle server. This can be a URL or IP.
1521 - port that the Oracle server listens to. 1521 is the standard port.
adisoft - SID of the database being used.
With an Oracle install, you'll probably endup changing some of these.
Database
Connection Strings
The ESS Installer uses the following database connection strings:
MySQL: jdbc:mysql//localhost/adisoft?zeroDateTimeBehavior=convertToNull
MS SQl Server: jdbc:microsoft:sqlserver://localhost:1433;SelectMethod=cursor
Oracle: jdbc:oracle:thin:@localhost:1521:adisoft
Installers will let you change these strings if you need to. The defaults will work if the database server is on the same machine as the app server. If you are not using one of the Installers, or you want to change the string after installation, you'll need to change the string in the system.xml file (ess/xmls), in the web.xml file (webapps/ess-app/WEB-INF) and on the 2 URLs used to generate the JavaScript profiles described below.
Security Settings
ESS reads and writes information to your hard disk in the form of xml files, log files and JavaScript files. In addition to being able to execute html and JSP, it is important that the user that launches the Tomcat service has the ablitily to create and write the following:
ESSProfile.js and AuditProfile.js - These files are located with your HTML in the 'ess' folder. The JavaScript profile generation maintenance process described below creates them.
/var/ess, c:\ess folder or equivalent - These folders will hold logs and user data that the system creates and adds to as it is run.
Folder from where Tomcat is started - In the event that the expense.log cannot be opened in one of the folders, it will attempt to open the log in the folder that it is pointed to when Tomcat is started.
Linux Security Note: Make sure that the user installing ESS has adequate privileges to modify the web and app server directories. Because user launching Tomcat has needs to have adequate privileges to write to the /var/ess folder and that user may be different from the user installing ESS, the Linux installation routine applies 777 as the privilege - protection level. System Administrators should review this folder, together with the user that launches Tomcat and make appropriate ownership and privilege changes.
Maintenance
From Time to time, you'll want to perform some basic maintenance on the Expense Submittal System.
1. Generate new ESS Profile JavaScript: After you've made changes to any of your control tables (e.g., expense types, payment methods, clients, projects), you'll want to generate new ESS Profile JavaScript (ESSProfile.js). ESSProfile.js is loaded into a reporters and approvers browser. It performs basic data validation. To generate a new ESSProfile.js, from your menu run the Expense Submittal System, ESS Profile Generation option. Enter the email address for the administrator (e.g., admin@yourcompany.com) and the password (adisoft). Here's an example of URL used to generate the ESS Profile JavaScript:
http://localhost/ess-app/ess/ESSProfile.jsp?database=jdbc:mysql://localhost/adisoft&folder=e:\apache2\htdocs\ess\
where:
database = JDBC connection string
folder = location of the ess html folder followed by a slash or backslash
Important: Currently, all profile generation must be done with IE.
2. Generate new Audit Profile JavaScript: After you've made changes to any of your control tables (e.g., expense types, payment methods, clients, projects), you'll want to generate new Audit Profile JavaScript (AuditProfile.js). AuditProfile.js is loaded into an auditor's browser. It performs basic data validation. To generate a new AuditProfile.js, from your menu run the Expense Submittal System, Audit Profile Generation option. Enter the email address for the administrator (e.g., admin@yourcompany.com) and the password (adisoft). Here's an example of URL used to generate the Audit Profile JavaScript:
http://localhost/ess-app/ess/AuditProfile.jsp?database=jdbc:mysql://localhost/adisoft&folder=/var/apache2/htdocs/ess/
where:
database = JDBC connection string
folder = location of the ess html folder followed by a slash or backslash
Important: Currently, all profile generation must be done with IE.
3. ESS logs all important actions to the 'expense.log' log. If you stick with the default settings, 'expense.log will either be in '/var/ess' or 'c:\ess'. You'll need to search your disk drive to find the exact location of the log. As 'expense.log' serves as an audit trail, it is never automatically deleted. Therefore, you'll want to backup up the log and delete it from time to time depending on your report volume.
Trouble Shooting
1. If you are installing on a system that has a firewall, especially XP, these sometimes interfere with conduits and connectors. If you are having problems accessing your app server via your Web server, disable your firewall and reboot the machine (from our experience, simply restarting the servers doesn't do the trick.
2. If you are installing on an application server only system, you will need to locate your html within the application (e.g., c:\tomcat\webapps\ess-app) and not as a separate application (e.g., not c:\tomcat\webapps). In addition, your Web server URL will include the application folder in the URL (e.g. http://localhost:8080/ess-app). In this case, you application server URL would be 'http://localhost:8080'.
3. If you can't log into ESS with the admin at your domain e-mail address, use 'backup@adisoft-inc.com', password is 'adisoft' and then modify the user profiles.
4. If you experience problems logging on, check the system table, XMLSYSTEM tag value, and make sure that the XMLS directory string is well formed. A value such as 'C:ess/xmls/system.xml' will cause problems. It should be 'C:\ess/xmls/system.xml' or 'C:/ess/xmls/system.xml' to work correctly.
5. If you experience database connectivity issues, make sure that the database user and password you specified in the setup are correct and have adequate privileges for the database. Also, if you are using Oracle and MS SQL Server, ensure you have the correct JAR files installed.
6. If you are having problems saving a report make sure the security on the xmls and xmlu folders allows the application server to create and write files. Also if the ESS fails on login with an AuditTrail in the dump, check the security on the ess folder.
7. The audit and admin functions do not yet fully support the Firefox browser. Until this has been addressed, you should use an IE browser when in the audit module.
Examples and
Suggestions for the ESS Installer
First suggestion: If you can take advantage of the ESA installers, do so. They install all the necessary components you need. Adisoft will also be able to support you easier as we’ll know your environment a little better.
If you must install Apache and/or Tomcat as part of this process, we suggest that you install Apache in folder c:\apache2 and that you install Tomcat in c:\tomcat4. The install defaults and examples below will be easy to follow. Otherwise, you need to substitute you locations for those provided below.
The examples below give you answers to the ESS install prompts.
Example 1: This example assumes that you have Apache and Tomcat installed as above and the there is a conduit, such as mod-jk, running between them. It also assumes that you are running everythinh under SSL (i.e., https:). Your domain is mycompany.com and you've setup MySQL as your database server. The user 'root', with a password of 'adisoft' has access to the adisoft database. We're assuming that the server you have installed ESS is assigned the URL of expenses.mycompany.com. Finally we assume that you SMTP server is call mail.mycompany.com.
Installation Directory: C:\Program Files\ESS-3
Location of scripts and xml database: C:\ess
Location of application server's webapps folder: C:\tomcat4\webapps
Location of your Web server's html folder: C:\Apache2\htdocs
Which database are you using: MySQL
JDBC connection string: jdbc:mysql://localhost/adisoft
E-mail domain name: mycompany.com
Expense email user address: expense@mycompany.com
SMTP server name: mail.mycompany.com
Web server URL: https://expenses.mycompany.com
App server URL: https://expenses.mycompany.com
Database user: root
Database user's password: adisoft
Example 2: This example is similar to the one above with the following exceptions. There is no Web server, just Tomcat. And there is no SSL. Instead of a URL, we'll just use the IP address of the machine we are installing on (e.g., 192.168.0.21). This is a good example for testing ESS out on the cheap. You literally only need to download tomcat and mysql, install them and you are good to go. Both of these installations only take minutes.
Installation Directory: C:\Program Files\ESS-3
Location of scripts and xml database: C:\ess
Location of application server's webapps folder: C:\tomcat4\webapps
Location of your Web server's html folder: C:\tomcat4\webapps\ess-app
Which database are you using: MySQL
JDBC connection string: jdbc:mysql://localhost/adisoft
E-mail domain name: mycompany.com
Expense email user address: expense@mycompany.com
SMTP server name: mail.mycompany.com
Web server URL: http://192.168.0.21:8080/ess-app
App server URL: http://192.168.0.21:8080
Database user: root
Database user's password: adisoft
The tricky thing about example two is that you need to define the web server as part of the application server.
Example 3: This example is similar to number one with the exception that we are going to use the Linux Installer instead of the Windows Installer. The Linux Installer is currently in beta and is available only at Adisoft's Web site. I've assumed that Tomcat and Apache are installed in the /var folder. Forewarned: I'd be the first to admit that I am not a Linux admin type so if you need to move things around, please do. The Linux install bin file can be run from the command line or through the run command from the menu. The experience is quite different between the two and I prefer that latter.
Installation Directory: /opt/ESS-3
Location of scripts and xml database: /var/ess
Location of application server's webapps folder: /var/tomcat4/webapps
Location of your Web server's html folder: /var/Apache2/htdocs
Which database are you using: MySQL
JDBC connection string: jdbc:mysql://localhost/adisoft
E-mail domain name: mycompany.com
Expense email user address: expense@mycompany.com
SMTP server name: mail.mycompany.com
Web server URL: https://expenses.mycompany.com
App server URL: https://expenses.mycompany.com
Database user: root
Database user's password: adisoft
Example 4: This is an example of installing ESS over the top of SpikeSource's free LAMP stack on a Linux box.
Installation Directory: /opt/ESS-3
Location of scripts and xml database: /var/ess
Location of application server's webapps folder: /opt/oss/share/tomcat/base/webapps
Location of your Web server's html folder: /opt/oss/share/apache2/htdocs
Which database are you using: MySQL
JDBC connection string: jdbc:mysql://localhost/adisoft
E-mail domain name: mycompany.com
Expense email user address: expense@mycompany.com
SMTP server name: mail.mycompany.com
Web server URL: https://expenses.mycompany.com
App server URL: https://expenses.mycompany.com
Database user: root
Database user's password: Mapinkbo
Make sure that '/var/ess' and its subfolders are completely accessible by the 'oss' user. This also applies to the ESSProfile.js and AuditProfile.js found in 'ess' under '/opt/oss/share/apache2/htdocs'.
Further Support and Registration
================================
More information and support can be obtained by registering at: www.adisoft-inc.com
####