Updated July 30, 2012
Software Setup
Here are some notes to help a developer get running with ZEPRS. Use the versions of the software (jdk, mysql) in the notes.
Install jdk 6, not jdk 7
Instal Mysql: 5.1.60 community edition. Add the following to the bottom of my.ini:
# zeprs
old_passwords=1
If you are using a newer version of mysql and do not have my.ini, check "old_passwords" in the configurator app.
Please note that if you don't have old_passwords set, authentication will not work.
Install ApacheTomcat 6.0.20.
Source Code
Source control can be integrated with the Eclipse IDE using Subversive. The
Subversive installation instructions are a useful guide to installing Subversive. Once it is installed and you restart Eclipse, go to File -> Import -> SVN and choose Project from SVN. Create a new repository using the URL http://www.ictedge.org/repos/zeprs/trunk/. Subversive will ask if you want to normalize the URL by truncating /trunk; don't do it.
If you are using a command-line subversion client, checkout the ZEPRS source code using the following comand:
svn checkout http://www.ictedge.org/repos/zeprs/trunk zeprs-readonly
Copy the folowing files from C:\source\zcore-workspace\workspace\zeprs\lib\ to C:\Program Files\Apache Software Foundation\Tomcat 6.0\lib
commons-dbcp-1.2.1.jar
commons-logging-1.1.jar
commons-pool-1.3.jar
log4j-1.2.13.jar
log4j.properties
- zcore-tomcat-realm.jar (Do not use tomcat-realm-zeprs.jar; it is obsolete.)
- mysql-connector-java-5.0.7-bin - Do not use mysql-connector-java-5.1.19-bin - this will cause problems with the population of lists.
Create the Databases
Using the mysql command, create the zeprs, zeprsdemo, admin, mail, and userdata databases.
Run the following sql scripts using the format mysql -u root db<file.sql
- conf/template/sql/zeprs-data-05032012.sql - create the zeprs db - mysql -u root zeprs<zeprs-data-05032012.sql
- conf/template/sql/zeprsdemo-data-05032012.sql - create the zeprsdemo db - mysql -u root zeprsdemo<zeprsdemo-data-05032012.sq
- conf/template/sql/admin_install.sql - create the admin db - mysql -u root admin<admin_install.sql
- conf/template/sql/mail_install.sql - create the mail db - mysql -u root mail<mail_install.sql
- conf/template/sql/userdata_install.sql - create the userdata db - mysql -u root userdata<userdata_install.sql
To configure the sql permissions, open conf/template/sql/web_user.sql and view the sql for the zeprs_web_user, root users. Lines 8 - 23 lines should suffice. You will need to replace "password" with the password for zeprs_web_user in META-INF/context.xml.
Eclipse Project Configuration
In Eclipse, go to Build Path -> Configure Build Path and point to your JDK's tools.jar.
Also confirm that the Server Runtime (Tomcat) points to a valid runtime. (Add Library -> Server Runtime.)
Add servlet-api.jar from your tomcat/libs directory.
Confirm that your server runtime is in eclipse preferences -> Server -> runtime environments
In the Servers view, add zeprs to the Tomcat 6 server. Also check in the projects properties Targgeted runtimes that it is pointed to this server.
Double-click on the server in Servers view. In the Server Locations section, Use tomcat installation and change the deploy path name to webapps.
It helps to increase the server timeouts to 90 seconds.
In Launch configuration arguments tab, put the following at the beginning of the VM arguments:
-Xms256m -Xmx1g -XX:MaxPermSize=256m
Copy local-example.properties to local.properties and configure the settings if you do anything in ant with build.xml.
Use Firefox to test the ZEPRS app; there is a bit of CSS work that must be done to get it to work in Chrome. See the
ZCORE ON TOMCAT 7 AND WINDOWS 7/64 BIT notes if you would like to upgrade ZEPRS to Tomcat 7 and/or Chrome.
Point your browser to localhost:8088/zeprs/
Troubleshooting
Lib path issues
When you start up the app, of you get the following error if zeprs-realm.jar is not in your tomcat/libs dir:
java.lang.ClassNotFoundException: org.apache.catalina.realm.UserGroupRoleRealm
If you get the error when you login:
SEVERE: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: SELECT command denied to user 'zeprs_web_user'@'localhost' for table 'accountuser'
revisit web_user.sql and run the credentials for that user.
Diagnosing Authentication Issues
Import the project into Eclipse. Right-click on the project name and select Build Path -> Configure Build Path. Confirm that the paths to the Libraries are correct.
In src/test, open ZcoreUserGroupRoleRealmTest. Right click on authenticate_shouldReturnAPrincipal and choose debug configuration. The following should be in the Classpath:
- tomcat-juli (in your Tomcat/bin folder)
- mysql-connect-java-5.0.5.jar (in your Tomcat/lib folder)
- commons-logging (in your Tomcat/lib folder)
- log4j.jar (in your Tomcat/lib folder)
Open ZcoreUserGroupRoleRealmTest. Enter the mysql login in the "String username" and String password" fields. Enter the username/password for the ZEPRS login you wish to test in the line "Principal principal = realm.authenticate... Hit the debug button and it should pass - check the Junit tab to confirm it is green. If the test fails, confirm that the settings in META-INF/context.xml are the same as the test config. Check the line in context.xml that starts with Realm className. Older version of this file user the name connectionName for username; change it to username:
Realm className="org.rti.tools.tomcat.ZcoreUserGroupRoleRealm"username="zeprs_web_user"
To step through the actual code for ZcoreUserGroupRoleRealm, right-click on the zeprs project properties and choose Build Properties -> configure build properties. In the Libraries tab open Apache Tomcat 6 library, and then open the zeprs-tomcat-realm.jar library (toggle the triangle widget). Click source attachment and edit. Browse to the location of the source code for the ZcoreUserGroupRoleRealm source code - will probably be /ZcoreUserGroupRoleRealm/src. Restart the app and try to login. If it fails, open src/ZcoreUserGroupRoleRealm and place a breakpoint "return this.username;"in the getUsername() method. Restart the app and see if it gets populated the next time you try to login.
-------------------
The following pages describe a few more details on the setup for ZEPRS development.
PDF version