Glen Mazza's Weblog

« Better Blogging with... | Main | Creating Selenium... »

https://web-gmazza.rhcloud.com/blog/date/20131216 Monday December 16, 2013

Hosting an Apache Roller blog on Red Hat OpenShift

Note: I've switched to TightBlog, which started off as a fork of Apache Roller in May 2015 and was released in July 2016. This blog is still on Roller however, awaiting OpenShift 3.0 availability before I switch to it.

Prefer a Wiki instead? See my JSPWiki on OpenShift entry.

This tutorial outlines the steps to deploy Apache Roller 5.1.0-SNAPSHOT (unreleased) on Red Hat's OpenShift public PaaS, the deployment used by this blog. I'm using the unreleased Roller version as it's been much simplified compared to earlier versions and almost all current development efforts are on this version, however, the latest release (5.0.3)--which may have fewer kinks--can also be used. I'll be deploying on JBossEWS 2.0 (Red Hat's commercial offering of Apache Tomcat 7.x and the Apache web server) using MySQL database and a Google Mail account to handle email notifications.

OpenShift is free within certain usage bounds, in particular three free "small gears" are provided. I'm deploying JBossEWS as scalable, meaning that it will take up more gears (up to the free maximum) as demands increase; however one of the three gears presently needs to be consumed by MySQL. (At a later date I hope to look into using Apache Derby for Roller instead of MySQL. With Derby on the JBossEWS gear(s) the MySQL installation can be deleted, freeing up a gear.) Note OpenShift also provides PHP-based WordPress as a blogging option; you may find Roller preferable if you're a Java developer and/or already have a JBoss or JBossEWS instance running on OpenShift to host your blog.

  1. Customize and build an Apache Roller war. Check out and build Apache Roller from trunk, i.e., 5.1-SNAPSHOT. Prior to building you may wish to add additional blog design (theme) options for your blog server--this blog uses the Rolling theme from the Roller-extras project. Next, you may wish to rename the roller.war generated to create a different URL path for your Roller blog (all blogs besides the default blog will have the blog handle added to that suffix). If you can, making Roller the default application by naming it ROOT.war (and deleting or renaming the already existing root application in the Tomcat webapps folder) will result in simpler URLs for permalinks--this is the approach I've taken for this blog. The following shows a URL comparison of a blog.war having a blog with handle of "gmazza" versus a ROOT.war with a blog handle of "blog":

    blog.war with blog handle of "gmazza":

    blog home:      http://web-gmazza.rhcloud.com/blog
    specific date:  http://web-gmazza.rhcloud.com/blog/gmazza/date/20131216
    specific entry: http://web-gmazza.rhcloud.com/blog/gmazza/entry/apache-roller-on-openshift
    

    ROOT.war with blog handle of "blog":

    blog home:      http://web-gmazza.rhcloud.com (also http://web-gmazza.rhcloud.com/blog)
    specific date:  http://web-gmazza.rhcloud.com/blog/date/20131216
    specific entry: http://web-gmazza.rhcloud.com/blog/entry/apache-roller-on-openshift
    

    If you'd like your blog to use SSL, either the entire site or just pages in which sensitive information will be transferred, uncomment and adjust the <security-constraint/> element in the Roller WAR's web.xml file as appropriate, following the comments above that element. Further, when you get to Step #4 below, update your OpenShift project's server.xml and context.xml files exactly as described in the "For Tomcat (JBoss EWS)" section of this OpenShift knowledge base article.

    At this stage, you may wish to do a test deploy of Roller on Tomcat running on localhost, following Chapters 5 and 6 of the latest Roller Install Guide (OpenOffice format) to confirm your WAR and desired system settings are working properly; most of those settings will carry over to your OpenShift installation, making the latter installation smoother.

  2. Create a new JBossEWS 2.0 application. Sign up for a free OpenShift account if you haven't already. From the applications page, choose Add Application and select the latest JBossEWS option. You'll probably want to choose the scaling option so JBossEWS can scale to additional gears if needs arise (scaling cannot be later added in if you don't choose this option when creating the application.) The name you choose becomes part of the subsequent URL for the application, for me I chose "web" giving me a base URL of web-gmazza.rhcloud.com, which can be replaced by purchasing a domain name. I'm avoiding an application name specific to what I'm deploying, to make the URLs sensible should I choose to host multiple web applications (.../blog, .../wiki, etc.) on the same JBossEWS instance.

    After creating a JBossEWS 2.0 instance, make sure you can accomplish the following three tasks before proceeding:

    • ssh into your instance where you can run standard *nix commands to maintain your application (checking Tomcat logs and configuring some files). For the SSH connection string, go to the OpenShift application page and click on the "Want to log into your application?" question.
    • Clone your application's repository to your local machine. Much of the Roller configuration will be placed into this repository and pushed to your OpenShift instance.
    • Install the rhc client tools and run rhc setup. These commands allow for remote administration of your OpenShift instance.

  3. Add MySQL to your JBossEWS application. From the OpenShift page for your application, select "Add MySQL 5.1" or from your local machine, enter the command rhc cartridge-add mysql-5.1 --app web substituting "web" with the name you chose for your application. This command will create a MySQL database hardcoded to the name of the application; however, if you're using JNDI, Apache Roller is configured by default to look for a database called "rollerdb"; also, as explained in Chapter 5 of the Roller Install Guide the MySQL database needs to be configured to use UTF-8. So, we'll delete this database and create one that Roller can use. To do this, ssh into the OpenShift server and run the following commands--change the username and password below to something more secure:

    [web-gmazza.rhcloud.com ...long string....]\>mysql
    mysql> drop database web;
    mysql> create database rollerdb DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
    mysql> grant all on rollerdb.* to scott identified by 'tiger';
    mysql> quit;
    mysql> set wait_timeout=90000;
    [web-gmazza.rhcloud.com ...long string....]\>exit
    

    Once Roller is installed and running you'll have easy access to the Roller database tables, just run mysql as above, enter use rollerdb; and enter whatever SQL statements desired, followed by a commit; for data changes. For example, I changed this blog's handle from "gmazza" to "blog" by updating the handle column in the website table, its corresponding objectid in the roller_permission table, and the site.frontpage.weblog.handle property in the roller_properties table (as this is the default blog). Then a commit followed by an app restart, and the new handle was activated.

    Besides using mysql at the ssh command-line to run queries, MySQL can also be accessed from your local machine, see Grant Shipley's article and video for some options.

  4. Create JBossEWS- and Roller-specific configuration files. Prior to deploying the Roller WAR, here are the configuration steps I followed:

    1. Move to the web/.openshift/config folder of the local copy of your application repository (obtained via git clone described in Step #3 above). Edit the file catalina.properties, adding the following new folders to the common.loader property:

      ${catalina.home}/../app-root/data/rollerdata/lib,${catalina.home}/../app-root/data/rollerdata/lib/*.jar

      The above setting is needed because the Tomcat lib folder where we would otherwise be placing configuration files and JARs is not accessible to the user on OpenShift JBossEWS, so we need to list additional folders for JBossEWS' classloader to look through.

    2. In the server.xml file in the same folder, add to the <Host/> element Roller configuration similar to the below, adjusted for your setup:

      <Context
        path="/blog"
        docBase="blog"
        antiResourceLocking="false">
        <Resource name="mail/Session"
          auth="Container"
          type="javax.mail.Session"
      
          mail.transport.protocol="smtp"
          mail.smtp.host="smtp.gmail.com"
          mail.smtp.port="465"
          mail.smtp.auth="true"
          mail.smtp.user="blah.blah@gmail.com"
          password="...email password..."
          mail.smtp.starttls.enable="true"
          mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
          mail.smtp.socketFactory.port="465"
          mail.smtp.socketFactory.fallback="false"
          mail.debug="true"
        />
      </Context>
      

      Update path and docBase above to what your Roller WAR is named. If you've made Roller the default application, i.e. ROOT.war, use "" and "ROOT", respectively, for these two values.

      The Google Mail configuration above is optional and primarily for for sending email notifications to the blogger when someone leaves a blog entry comment, either just as an FYI or for moderation before the comment is published. Probably best to create a new email account for this purpose rather than relying on a personal email address, as the server configuration requires a hardcoded email username and password potentially viewable by others. Using mail services other than GMail should also work fine. To activate emails, see Section 6.2 of the Roller Install Guide for servlet container configuration and Sections 7.1.3 and 9.2 of the Roller User's Guide for Roller configuration. This step is optional not only if you're not intending to use the emailing feature but because OpenShift will send the notification emails using its own "no-reply@rhccloud.com" account if you don't do your own email configuration.

    3. ssh into your application and create a rollerdata/lib folder structure under app-root/data. In this lib folder add the JARs described in Section 6.3 of the Roller install guide, namely the MySQL JDBC Driver and JavaMail's javax.mail-1.5.0.jar (the latter, required whether or not you'll be using emailing features). SCP or WinSCP provides an easy way to transfer files from your local machine to your OpenShift instance:

      scp mysql*.jar {appUUID}@web-gmazza.rhcloud.com:app-root/data/rollerdata/lib 
      

      Where the URL string above will need modification based on your application URL and {appUUID} is your Application UUID, obtainable from your local machine by running the rhc apps command or via whoami when logged into the OpenShift server.

    4. In the same lib folder we'll need to add the roller-custom.properties files containing our Roller configuration overrides (doable also via the SCP command above or editing a file after SSH'ing into OpenShift), similar to:

      installation.type=auto
      mediafiles.storage.dir=/var/lib/openshift/{appUUID}/app-root/data/rollerdata/mediafiles
      search.index.dir=/var/lib/openshift/{appUUID}/app-root/data/rollerdata/searchindex
      log4j.appender.roller.File=/var/lib/openshift/{appUUID}/jbossews/logs/roller.log
      log4j.logger.org.apache.roller=INFO
      
      #MySQL
      database.configurationType=jdbc
      database.jdbc.driverClass=com.mysql.jdbc.Driver
      database.jdbc.connectionURL=jdbc:mysql://{host:port}/rollerdb?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&mysqlEncoding=utf8
      database.jdbc.username=????
      database.jdbc.password=????
      
      #Mail
      mail.configurationType=jndi
      mail.jndi.name=mail/Session
      

      Where:

      • {appUUID} is defined as earlier.
      • {host:port} is obtainable by running "echo $OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT" while logged into the OpenShift server.
      • the database username and password is for the user granted access to the rollerdb database (the "scott" and "tiger" listed above), not the MySQL admin username and password.
  5. Upload the Apache Roller WAR to your OpenShift JBossEWS instance. Best to use the SCP method to upload the Roller WAR instead of uploading it via the Git repository. That's because the git repository storing your changes count against your gear's 1GB space limitation, and binary WAR updates in Git will quickly consume that space.

    Important: By default, OpenShift's haproxy bombards the JBossEWS root application with GET requests every two seconds to confirm the JBossEWS instance is running well. If you've decided to host Roller as the default application (ROOT.war), it will receive that bombardment, resulting in your blog reporting 1000's of hits each day and frequently filling up the Catalina error logs with "broken pipe" messages as Roller usually can't handle requests that rapid and continuous. To fix this, increase the pinging interval, disable the pinging entirely, or have it ping another webapp by altering the option httpchk setting in the haproxy.cfg file in your OpenShift instance. For my Tomcat instance I decreased the pinging to once per minute and had it ping an empty webapp: option httpchk GET /scalechk/, with a new jbossews/webapps/scalechk "application" containing only a static index.html file.

    Finally, do a git add/commit/push to place the configuration files in your local web/.openshift folder to the JBossEWS instance. (Important: You will always need to do a git push after making changes in your .openshift folder to propagate them to your OpenShift application.) The action hooks defined in your project will automatically shutdown and restart the Roller application as part of the git push. If all goes well you should now be able to access your Roller installation at http://{appname}-{accountname}.rhcloud.com/{war name} and continue the standard Roller automated setup. Roller will create the database tables for you and guide you into creating your first blog, etc., as described in the Roller Install Guide. Before continuing, make sure you can create a blog, a blog entry, and (if you've configured Roller to do so) that you're receiving email notifications for new comments. The Roller User's Mailing List is available should you have any configuration difficulties.

  6. Perform post-installation configuration. Once everything appears to be running fine it would be good to reduce system logging and remove unneeded webapps in order to limit server usage and speed Roller performance. Some suggestions:

    1. For safety and performance you will probably want to remove any pre-installed applications under webapps/ in your JBossEWS installation.

    2. Reduce Tomcat logging: Logging configuration is done in {appname}/.openshift/config/logging.properties of your Git application repository. Changing the Catalina logging from FINE to WARNING will considerably reduce the amount of logging stored in the catalina.out and catalina.{date}.log files:

      1catalina.org.apache.juli.FileHandler.level = WARNING  
      java.util.logging.ConsoleHandler.level = WARNING
      

      Other worthwhile suggestions include deactivating the catalina.out and any unused loggers (e.g., the manager and host-manager loggers if you don't have their corresponding applications installed.)

    3. Shut off the Tomcat AccessLogValve: this logs whenever a GET or a POST is made against Tomcat, it can be deactivated by commenting it out within the .openshift/config/server.xml file:

      <!--Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
          prefix="localhost_access_log." suffix=".txt"
          pattern="%h %l %u %t "%r" %s %b" /-->
      
    4. Reduce the Roller logging down to WARN level: Roller is extremely chatty at the INFO level, setting its logging level to WARN (not WARNING) in the roller-custom.properties is preferable for post-installation use:

      log4j.logger.org.apache.roller=WARN
      

Notes/Additional Resources:

  • Sometimes the git push origin master command fails to reactivate the MySQL database even as it will still activate JBossEWS. You will be able to see by logging into your account from OpenShift website and checking your application's status page (https://openshift.redhat.com/app/console/application/{appID}). If this occurs a manual rhc app stop {appname}/rhc app start {appname} from your local machine should fix the problem.
  • Better Blogging with Apache Roller - Learn about blog backups, setting up Google Analytics, blog widgets, etc.
  • OpenShift documentation
  • The OpenShift Forum is available for community-based help.
  • If the web application becomes inoperative and you can't ssh into your OpenShift account, it may be an out of memory or threads issue. Best to run the rhc app stop appName command (or, if necessary, the stronger rhc app force-stop appName) from your local machine followed by another ssh attempt where you can then work to fix the problem with your application.
  • See this note for using a more friendly domain name besides the standard appname-accountname.rhcloud.com.

Comments:

Hello Glen, Love your site! I just installed roller on our linux server and would like to change the URL of the blog from: http://mailer.ncsplus.com:8080/roller/ to: http://blog.ncsplus.com I have control of the DNS. Do you know how to do this. Any help is much appreciated! Chris.

Posted by Christopher Rehkow on June 21, 2016 at 03:26 PM EDT #

Hi Chris! Welcome to Roller (well, at least for the next month before you upgrade to TightBlog) -- In your roller-custom.properties file, update the site.absolute URL value (https://github.com/gmazza/tightblog/blob/master/app/src/main/resources/org/apache/roller/weblogger/config/tightblog.properties#L185) with that new URL, and restart Roller. Regards, Glen

Posted by Glen on June 21, 2016 at 03:32 PM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed

Valid HTML! Valid CSS!

This is a personal weblog, I do not speak for my employer.