Glen Mazza's Weblog

Updated July 2016.

This entry explains how to set up a development environment and process for working on the Java-based TightBlog blog server. The tools below are the ones I use, some are optional some (such as preferred IDE or database to use) can be modified to your preference.

Tool list for programming TightBlog:

1. Fork TightBlog and add any desired additional themes - Do a git clone git@github.com:gmazza/tightblog.git from the command-line window. You can also make a fork within GitHub to work from your own account. If you have any of custom blog themes to add, place them in the src/main/webapp/themes folder prior to building TightBlog. Make sure TightBlog build (including JUnit tests) runs successfully before proceeding further.

2. Prepare database and (optional) mail configuration - Follow the short Chapter 5 and Chapter 6, Sections 1-4 of the Roller Install Guide (ODT), except name your override file tightblog-custom.properties instead of roller-custom.properties. Chapter 5 provides the few commands needed to configure an empty MySQL, PostgreSQL, or Derby database and Chapter 6 the configuration of the tightblog-custom.properties file, optional Mail configuration, and the required Mail and JDBC JARs that will be needed in Tomcat's lib folder. The test tightblog-config.properties file that I have in my Tomcat lib folder is as follows:

   # Any properties placed below overrides TightBlog default settings defined in
   # the tightblog.properties file embedded within the TightBlog WAR, and should be 
   # stored in the CATALINA_HOME/lib folder for Tomcat.
   
   installation.type=auto
   mediafiles.storage.dir=/home/gmazza/work/tightblog-dbs/mediafiles
   search.index.dir=/home/gmazza/work/tightblog-dbs/searchindex
   
   #Derby
   database.configurationType=jdbc
   database.jdbc.driverClass=org.apache.derby.jdbc.ClientDriver
   database.jdbc.connectionURL=jdbc:derby://localhost:1527//home/gmazza/work/tightblog-dbs/MYTBDB
   database.jdbc.username=app
   database.jdbc.password=app
   
   # EclipseLink debugging (filepath cannot be simplified via ${catalina.base} as above)
   eclipselink.logging.file=/home/gmazza/work/apache-tomcat-8.0.30/logs/eclipselink-tomcat.log
   eclipselink.logging.level=FINER
   
   # Mail config (See Roller Install Guide)
   mail.configurationType=jndi
   mail.jndi.name=mail/Session
   

   Before moving on to the next step, best to deploy the app/target/tightblog.war to your Tomcat webapps directory, start Tomcat and confirm you can run the application at http://localhost:8080/tightblog. This is an important one-time check to ensure your database, tightblog-custom.properties file, Tomcat, and TightBlog WAR are all properly configured, and once confirmed you should be in good shape for all subsequent coding and debugging. If any deployment problems, make sure you've reviewed Chapters 5 and 6 of the Install Guide.

3. Create a script to start development with everything needed - For efficient start-up I've created a hacktb.sh script that opens up all needed windows and applications at once instead of having me needing to do so manually each time I start development. A simplified version of my hacktb.sh is as follows and explained below:

   hacktb.sh:

   gnome-terminal --geometry=132x24 \
      --tab-with-profile=HasTitle --title "TB Trunk" --working-directory ~/work/tightblog \
      --tab-with-profile=HasTitle --title "TB Trunk2" --working-directory ~/work/tightblog -e "bash -c \"echo -Dmaven.surefire.debug; exec bash\"" \
      --tab-with-profile=HasTitle --title "Servlet Container" \
      --tab-with-profile=HasTitle --title "IntellijIDEA" -e "bash -c \"sh idea*/bin/idea.sh; exec bash\"" \
      --tab-with-profile=HasTitle --title "Derby Network" --working-directory $DERBY_HOME/bin -e "bash -c \"startNetworkServer; exec bash\"" \
      --tab-with-profile=HasTitle --title "GEdit" -e "gedit worklog.txt hacktb.sh $CATALINA_HOME/lib/tightblog-custom.properties $CATALINA_HOME/logs/catalina.out $CATALINA_HOME/logs/tightblog.log `find $CATALINA_HOME/logs/localhost*.log` $CATALINA_HOME/logs/eclipselink-tomcat.log " \
      --tab -e "dolphin --geometry=600x500+1+1 tightblog-dbs tightblog $CATALINA_HOME" \
      --tab -e "google-chrome https://github.com/gmazza/tightblog/issues http://localhost:8080/tightblog" \
      --tab-with-profile=HasTitle --title "SquirrelSQL" --working-directory ~/work/squirrel-sql-3.7 -e "bash -c \"sh squirrel-sql.sh; exec bash\""
   

   The above script opens a multitab Console window which in turn opens a few separate application windows. In particular:

   • I open two terminal tabs pointing to the TightBlog code. This allows me to build TightBlog from one terminal while reviewing my changes (using commands git status and git diff, etc.) in the second window. I echo the -Dmaven.surefire.debug in the second tab as a reminder of the Maven string to add during JUnit test debugging (covered below).
   • I have a separate "ServletContainer" tab open to my home folder for manual activation of servlet containers (Tomcat normally) or other applications from the command line. I don't need this as often due to the copy.sh script (discussed below) I now use.
   • I use a tab for starting IntelliJ IDEA.
   • I use Derby's Network mode (startNetworkServer) instead of its Embedded mode so the database can be accessed by multiple JVM's (one by Tomcat and the other by Squirrel SQL).
   • I open the multi-tab GEdit text editor with several files that are handy for me during development:
     • worklog.txt - A scratchpad file of TODO notes, commands, etc. that I keep for personal use between coding sessions.
     • hacktb.sh - The very script above, I keep handy in case I need to make adjustments or additions to it.
     • tightblog-custom.properties - The configuration file discussed above and used by all TightBlog deployments to my standalone Tomcat. Changes I made here are activated on the next Tomcat restart.
     • catalina.out, tightblog.log, localhost*.log, eclipselink-tomcat.log - These are logging files filled by Tomcat and/or TightBlog during running, usually very important for debugging as error logging usually gets written to one of these files. If you see any terse "System" or similar errors reported by TightBlog in the web browser be sure to check these files for the error in detail.
     • tightblog.log, eclipselink.log - These files are under TightBlog's target directory and are populated during JUnit test running via the Maven test phase, as discussed below.
   • Dolphin - A multitab file browser that I have opened to the TightBlog trunk code, database files, and Tomcat folders for easy access to files.
   • Firefox - Here I pre-open tabs to the TighBlog website and default webpage location for TightBlog once it's deployed to Tomcat.
   • SquirrelSQL - Commented-out by default but used when I wish to query the TightBlog database to see the values that TightBlog is reading/writing. SquirrelSQL will need your database's JDBC JAR added to it as well as have the connection information configured in tightblog-custom.properties.

   For scripts such as the above make sure there's no whitespace after the ending "\" on each line (error messages will pop up otherwise), and use a leading # (as shown above for SquirrelSQL) for actions you wish to disable by default. The $CATALINA_HOME specified above, as usual, is the base folder for your standalone Tomcat installation.

4. How to build and deploy to local Tomcat - After a successful mvn clean install from the TightBlog trunk folder, I run this copy.sh shell script that I keep in that folder:

   fuser -k 8080/tcp 8009/tcp 8005/tcp
   rm -r $CATALINA_HOME/webapps/tightblog
   cp ./app/target/tightblog.war $CATALINA_HOME/webapps
   rm $CATALINA_HOME/logs/*.log
   rm $CATALINA_HOME/logs/catalina.out
   $CATALINA_HOME/bin/startup.sh
   

   For rapid iteration when I don't need to run the tests each time, I simplify my build and deploy process to a single line: mvn clean install -Dmaven.test.skip ; sh copy.sh.

   The above file first kills the Tomcat instance (via fuser -k), deletes the previous expanded TightBlog webapp directory on the Tomcat instance and copies the latest created TightBlog WAR over, and clears all the logs before finally restarting Tomcat with the new WAR. The new TightBlog will be accessible at http://localhost:8080/tightblog again using the same $CATALINA_HOME/lib/tightblog-config.properties and database (i.e., all database-stored information including test blog data created will be immediately picked up by the new TightBlog WAR.)

5. How to debug on local Tomcat - Learning to debug from your IDE any webapp running locally on standalone Tomcat is frequently vital when troubleshooting and thankfully simple to do. First, add to your Tomcat CATALINA_OPTS environment variable:

   export CATALINA_OPTS=$CATALINA_OPTS" -Xdebug -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n"
   

   Then from IntelliJ IDEA (or Eclipse), go to menu item Run -> Edit Configurations, add a Remote Configuration with a name of your choice and accepting the given defaults, and select OK. If TightBlog is already running on Tomcat, debugging can be activated at any time by setting breakpoints in the code that the TightBlog app would be activating, selecting menu item Run --> Debug {debug config name}, and then proceed with any needed code tracing.

6. How to debug unit tests - To activate a specific TightBlog JUnit test, navigate to the tightblog/app folder and run mvn test -Dtest=TestClassName#OptionalTestMethodName, as explained in the Maven Surefire Plugin documentation. To debug (code trace) the JUnit test within your IDE, add the -Dmaven.surefire.debug setting, set breakpoints in your IDE within code called by the tests and have it listen to port 5005 as before.

   Files to read: When running the JUnit tests, besides the Surefire results in the target/surefire-reports folder the target/tightblog.log file provides logging of the temporary in-process TightBlog instance. Also, to determine any potential SQL/JPA problems, EclipseLink JPA logging can be activated, with the output file also in the target folder, by uncommenting the eclipselink.logging.* properties in the app/src/test/tightblog-custom.properties file.

7. How to run Selenium tests - TightBlog's Selenium tests test very basic functionality (setting up a blog and saving a blog entry) but can sometimes serve as a quick sanity check that minor, last-second source code changes did not cripple the application. Navigating to the trunk/it-selenium folder and running mvn clean install will cause a temporary instance of TightBlog to activate that is subsequently used by Selenium to run its tests in Firefox. For these tests, none of the database or Tomcat configuration created above will be used, instead TightBlog will be running an embedded Jetty and a temporary (in-memory) Derby database, and shut down once Selenium is finished.