Blandware AtLeap Installation Instructions

Common preliminary steps

1. Read SoftwareRequirements and install which you need. Install Java applications into directories without spaces e.g. C:\Program files\
2. Set a JAVA_HOME environment variable which points at your Java Development Kit installation e.g. set JAVA_HOME=C:\java\jdk1.5.0_02
3. Configure your JVM (Java Virtual Machine) see JavaConfiguration
4. Set an ANT_HOME environment variable which points at your Apache Ant installation e.g. set ANT_HOME=C:\java\apache-ant-1.6.5
5. Download the latest version of Blandware AtLeap https://atleap.dev.java.net/servlets/ProjectDocumentList
6. Unpack distributive using proper util e.g. WinZip under Windows or unzip under Unix.
7. Run all below commands from directory into which you unpack AtLeap 1 Possibly under Unix you should run chmod a+x bin/*.sh
8. Check the correctness of each file using command bin\build.bat check-md5 for Windows or bin/build.sh check-md5 for Unix
   AtLeap provides build.xml file for Apache Ant and you can use it directly to perform some Ant task e.g. ant check-md5. Additionally AtLeap provides OS dependent bin scripts BAT for Windows and Shell for Unix. It provides extra checks for Java and Ant. I recommend to use them ever if possible. For simplicity below we will write bin/build for both OS.

Blandware AtLeap Quick start of demo

AtLeap has embeded Hypersonic DBMS and Jetty servlet-container. They are for demonstration purposes. I do not recommend you to use them in production mode for performance and stability reasons.

• In order to run demo version of AtLeap merely type bin/start-demo
• In order to shutdown server with AtLeap demo type bin/stop-demo

Configuring for one of supported Application Servers

1. Set a home enviroment variable of your application server e.g. CATALINA_HOME, RESIN_HOME, JBOSS_HOME etc. which points at your servlet container e.g. C:\java\jakarta-tomcat-5.5.9
2. If you plan to use Security Manager configure your application server policy file according SecurityConfiguration
3. Confugure properties in build.properties file according instructions in it. It is recommended to create atleap-build.properties file in the same directory which will override properties from build.properties file and keep build.properties untouched.
4. Specify appserver.host correctly.
5. Comment out the properties of default application server Jetty in Jetty section.
6. Uncomment properties from section of required application server. As minimum you need to uncomment:
   1. appserver.type
   2. appserver.http.port
   3. appserver.https.port
7. Other properties should be uncommented only in special circumstances

Please be sure that all paths configured in Directory Properties section have write permissions to user under which you run your container.

Database configuration

In order to enable some DBMS please uncomment all properties from the section of required DBMS and configure them correctly.

if you have the database created by previous version of AtLeap please drop it and create again.

MySQL configuration

1. For MySQL 4.1 and above you should run mysql daemon with parameter --default-character-set=utf8
2. MySQL is the DBMS which provide facility to add database dynamically if you have admin rights. In this case you can run bin/build setup and script make all work for you. Otherwise
   1. Ask your administrator to create DB for you
   2. Create DB tables, using command bin/build db-prepare
   3. Load initial data, using command bin/build db-load
   4. Cleans, undeploy and re-deploy application bin/build refresh

PostgreSQL configuration

1. Be sure that PostgreSQL is listening on TCP/IP
2. Create unicode database manually or ask your administrator
3. Create DB tables, load initial data, cleans, undeploy and re-deploy application bin/build setup

Oracle configuration

1. AtLeap distributive does not include Oracle JDBC driver, please download it from the site http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html
2. Rename JAR accroding lib/lib.properties file e.g. ojdbc14-10.1.0.jar (or change version number in lib/lib.properties file)
3. Put JAR into appropriate dir according lib/lib.properties file e.g. lib/ojdbc-10.1.0
4. Create Oracle user and schema and give all required permissions to it
5. Create DB tables, load initial data, cleans, undeploy and re-deploy application bin/build setup

Derby (NetworkServer) configuration

1. AtLeap distributive does not include Derby JDBC driver, please download Derby from the site http://db.apache.org/derby/derby_downloads.html and get lib/derbyclient.jar
2. Rename JAR accroding lib/lib.properties file e.g. derbyclient-10.1.1.0.jar (or change version number in lib/lib.properties file)
3. Put JAR into appropriate dir according lib/lib.properties file e.g. lib/derbyclient-10.1.1.0
4. Run Derby network server
5. Create DB tables, load initial data, cleans, undeploy and re-deploy application bin/build setup

Derby (Embedded) configuration

1. AtLeap distributive does not include Derby JDBC driver, please download Derby from the site http://db.apache.org/derby/derby_downloads.html and get lib/derby.jar
2. Rename JAR accroding lib/lib.properties file e.g. derby-10.1.1.0.jar (or change version number in lib/lib.properties file)
3. Put JAR into appropriate dir according lib/lib.properties file e.g. lib/derby-10.1.1.0
4. Cleans, undeploy and re-deploy application bin/build refresh (DB tables will be created and initial data will be loaded automatically during deployment)

MS SQL configuration

1. AtLeap distributive does not include MS SQL JDBC driver, please download open source jTDS driver from the site http://jtds.sourceforge.net/
2. Rename JAR accroding lib/lib.properties file e.g. jtds-1.1.jar (or change version number in lib/lib.properties file)
3. Put JAR into appropriate dir according lib/lib.properties file e.g. lib/jtds-1.1
4. Create MS SQL database and user for it
5. Create DB tables, load initial data, cleans, undeploy and re-deploy application bin/build setup

IBM DB2 configuration

1. AtLeap distributive does not include DB2 JDBC driver, you can get it from your DB2 installation e.g. IBM/SQLLIB/java e.g. db2jcc.jar, db2jcc_license_cisuz.jar and db2jcc_license_cu.jar
2. Rename main JAR accroding lib/lib.properties file e.g. db2jcc-8.2.jar (or change version number in lib/lib.properties file)
3. Put all JARs into appropriate dir according lib/lib.properties file e.g. lib/db2jcc-8.2
4. Create DB2 database and user for it
5. Create DB tables, load initial data, cleans, undeploy and re-deploy application bin/build setup

Other database configuration

1. Download JDBC driver
2. Create a record in the lib/lib.properties file
3. Put the driver into directory which you have just specified in lib/lib.properties file
4. Make a record in build.properties file according driver documentation, Hibernate documentation and DBUnit documentation
5. Create a database if it required
6. Create DB tables, load initial data, cleans, undeploy and re-deploy application bin/build setup

Start your AS if it is not started and open http://localhost:8080/atleap in your browser.

Troubleshooting

Errors during deployment

Tomcat has a bug with deployment of big WAR (Web archive) and AtLeap is big WAR. If you get one of the following errors during atleap deployment

• Missing application web.xml
• cannot create JDBC driver of class ' ' for connect URL 'null'
• Error deploying application at context path null
• or something like

1. Stop tomcat
2. Specify deploy.force.unpack=true property in your build.properties file
3. bin/build refresh
4. Start tomcat

Out of memory

Out of memory: PermGen space

Could not reserve enough space for object heap

Please carefully read documentation and release notes of your servlet container to avoid extra problems. For example Tomcat under Linux recommends to define LD_ASSUME_KERNEL environment variable equal to the kernel version (e.g. 2.4.1).

-- AndreyGrebnev - 04 July 2006