Steps for manually installing ESS
Version 7
Thursday, May 5, 2013
Copyright
2006, 2013 R.James Holton, All rights reserved.
This process is used to install ESS from the ESS-7.nnn.zip
on a Web, application and database server.
To run ESS, you need to have a functioning application
server such as Tomcat. You need to have
a functioning database such as MySQL. In
addition, you'll probably want to have a functioning Web server such as
Apache. If you have a Web server, and
this is the best, you will need a conduit between your Web server and your
Application server such as mod_jk or use proxy_ajp to force Apache to act as a
proxy for Tomcat. This allows you to
address the Application server folders through your Web server URL or IP. Don't
panic if you don't have these installed yet. See note 1 below.
Expenseservices.com uses, and has tested ESS on Linux and Window's stacks
consisting of Apache2, Tomcat, MySQL and
conduits (mod_jk and proxy_ajp).
Note 1: If you don't have a stack that will support ESS
already on your server, the easiest way to install the components for review is
to get a stack installer from BitNami.org. BitNami provides TomcatStack (http://bitnami.org/stack/tomcatstack)
which has all the necessary components required by ESS. There is a separate
document in this documentation that shows you how to install BitNami's
TomcatStack so it will run with ESS.
TomcatStack uses Apache as a proxy for Tomcat so all applications are
installed under Tomcat and there is minimum configuration required. Here are some procedures that will allow
you to install the Tomcat BitNami stack.
Note 2: We no longer distribute, through SourceForge.net, the SQL scripts and
configuration files for Oracle. If you want these items, you should contact
"service@expenseservices.com".
We currently are distributing MySQL and MS SQL Server configuration files via
SourceForge.net. The MySQL files are an inherent part of the release. The MS SQL Server files are available in the resources/msssql folder.
Note 3: We’ve also run ESS on IIS, JRun, ODBC. A goal in ESS coding was to make it
non-environment specific.
Note 4: Currently ESS needs the "AddDefaultCharset ISO-8859-1" set in
the Apache httpd.conf file. We plan on
changing to UTF in future releases.
If you don’t understand the previous paragraphs, you should
seek technical support. The manual
installation of ESS is not “hard,” but it does require a good degree of
familiarity with your Web, application and database servers. The instructions below will require you to create
a significant number of folders and links.
Follow these steps to install ESS once your servers have
been setup:
- Unzip
the contents of the ESS.{ver}.zip file into your home or a work folder
(aka., {home}). Move the folder ess into the /var folder. If you have a
Windows machine you should create a /var folder. It you decide not to have
a /var folder, or call it something else, you can, but you will need to
modify the MySQL dabase, specifically the XMLSYSTEM element row in the
SYSTEM table to point to the location of the system.xml file. You also
need to modify the contents of the system.xml file. It is simplier and
better for support to have a /var folder (Note: The Bitnami Amazon Cloud
instance I used does not come with unzip installed. I was able to install the unzip package
with “sudo aptitude install unzip”).
- If you
are using a database other than MySQL or ODBC, you’ll need to copy your
JDBC driver jar files to /var/ess/application/webapps/ess-app/WEB_INF/lib
folder. You'll also need to copy several other configuration files to the xmls folder. For more information
consult the Readme.txt in the resources folder for your database. You can skip this step if
you are using MySQL which is the default.
- Next,
you need to create symbolic links from the server folders (apache, tomcat
and mysql) to the appropriate application and data folders. Create these
three links:
- From Apache's htdocs
folder, make ess => /var/ess/application/htdocs/ess, if using BitNami,
or proxy_ajp make this link in Tomcat's webapps folder.
- From Apache's htdocs
folder, make receipts => /var/ess/application/htdocs/receipts, if using
BitNami, or proxy_ajp make this link in Tomcat's webapps folder. This folder needs to be writable by the
Apache application.
- From Tomcat's webapps
folder, make ess-app => /var/ess/application/webapps/ess-app
- From MySQL's data
folder, make ess => /var/ess/data/ess
- There
are specific examples in the installation
notes for creating symbolic links on each platform.
Consult installation notes for syntax on various
systems.
- The
‘@@strings@@’ in the configuration files represent specific
addressing. We want to replace the
‘@@strings@@’ with information that is valid for your installation.
- Edit the
/var/ess/xmls/system.xml file to provide the correct information regarding
your email system.
- exp_email_address ( @@emailname@@ ) - The email account that will be used by
ESS to send out workflow and informational messages. Example: expense@mycompany.com
- smtp_address ( @@smtp@@ ) - This is the URL of the SMTP server that ESS
will use to send out e-mail messages.
Example: mail.mycompany.com
- smtp_domain= ( @@domain@@ ) - The general domain of your company. Example: mycompany.com
- pal_email_address = ( @@emailname@@ ) - The email account that will be used by
ESS to send out workflow and informational messages. Example: expense@mycompany.com
- dump_mail = ( @@emailname@@ ) - same as above.
- If you are supporting the
acceptance of receipt scans by phone or email you need to set up a
separate POP3 mailbox to act as a gateway in collecting the scans. Do not
use the address that you send ESS mail from as this will cause confusion
in handling incoming messages. To edit the gateway and POP3 elements for
the gateway, in the configuration section of system.xml edit:
- Gateway_interval –
Interval in minutes that ESS will look for messages in the POP3 mail box.
- Gateway_stop_time –
Recommend setting to ‘No’.
- Pop3_logon – The login
ID to the POP3 mail box that serves as the gateway.
- Pop3_password – POP3
password
- Pop3_delete_messages –
Normally set to ‘Yes’. ‘No’ is
used for debugging.
- Pop3_address – Address
of the POP3 server.
- Edit the
/var/ess/application/webapps/ess-app/WEB-INF/web.xml file for the root
user
- @@dbuser@@ - login user
for access to the database. Example: root
- @@dbpassword@@
password used to access database. Example: MyPassword
- It may be necessary to
modify the port number used to access MySQL in the DBDatabase
context-param. The current string being used is:
jdbc:mysql://localhost:3306/ess?zeroDateTimeBehavior=convertToNull
- The number 3306 is the
port number and should correspond to the port used when MySQL was set up.
The MySQL port default is 3306.
- If you are supporting
the acceptance of receipt scans by phone or email, you may want to
activate the ReceiptConduitLaunch listener class. This will run a background task when
Tomcat is started that is responsible for polling the email box
associated with downloading the receipt scan files. Remove the "comment-" characters from the
beginning and ending name tags for listener that contains
the ess.ReceiptConduitLaunch class
to activate this feature. Consult the webFullVersion.xml file in
the WEB-INF folder as to what an active ess.ReceiptConduitLaunch class
element should look like.
- Edit the
/var/ess/application/webapps/ess-app/WEB-INF/classes properties files for
@@expensereport@@. This should be
set to the URL of the server that is running ESS. Currently there are two properties files.
One is for English and the other is for French.
- The web.xml file also
controls LDAP support. You should get the ESS application up and running
independent of LDAP and then switch to LDAP. Consult the LDAP Integration
document for setting LDAP up.
- Make sure that the security
on /var/ess/data/ess allows it to be accessible to Tomcat. In Linux this can be accomplish by
setting the ess folder and its contents to the same owner and group
as Tomcat (sudo chown -R owner:group /var/ess). Also you may have to ensure that the data
files are read and writable (sudo chmod 666 *)
- Restart the Tomcat server.
(Under BitNami, use the ctlscript.sh restart function to do this)
- Test the reporter/approver
login with one of the following three URLs:
o
http://{your server
address}/ess/en/XLogin.html
login = reporter@expenseservices.com, password = password
(reporter in English)
o
http://{your server address}/ess/en/XLogin.html
login = approver@expenseservices.com, password = password
(reporter/approver in French)
o
http://{your server
address}/ess/ess/Login.html
login = reporter@expenseservices.com, password = password
(Legacy)
[Note: Reporter's reports are send to Approver for approval]
- Test the audit login with the
following URL:
o
http://{your server
address}/ess/ess/Audit.html
Login = admin@expenseservices.com, password = password
(auditor in English)
(You can also access the audit and admin menu from the 'Admin' link on the
reporter login)
====