Deploying AtomServer

Chris Berry, Bryon Jacob. Updated 11/2/08

This document describes specific details about deploying AtomServer. Basically you have three options;

• Standalone AtomServer.
  
• Deploy AtomServer as a War.
• Configuring Tomcat
  
• Embed AtomServer as a Jar within your webapp.

You should also take a look at these;

• Required variables when starting up AtomServer.
  

---

Standalone AtomServer

This is the easiest way to deploy AtomServer.  Simply:

1. Download the tar.gz (available here)
2. Un-tar it (at, say, ATOMSERVER_HOME)
   
3. Start it up. ($ATOMSERVER_HOME/bin/atomserver.sh)
   

The tarball comes with an embedded Jetty Servlet Engine, the recommended project structure, example configuration files, and example workspace data.

Using the standalone AtomServer is explained in detail in the Getting Started document, so we won't repeat that information here.

---

Deploying AtomServer as a War.

To deploy AtomServer as a War you will mostly just

1. Download the War (available at our maven repository)
2. Drop it into your Servlet Engine of choice.
3. Set the required AtomServer System properties. Somehow passing them through your Servlet Engine's start script.
4. Start it up.

Configuring Tomcat.

Let's use Tomcat as a example. And to simplify the following discussion, lets start from the downloaded tar.gz. This is simpler because the tarball comes with a proper configuration, so we can avoid having to explain that as well. The directory structure and files laid down by the tarball are explained in detail by the Getting Started document. You will be starting up with the provided; myenv.properties from our demo server.

1. Download the AtomServer tar.gz (available here)
2. Un-tar it. Lets assume that you did this at ~/work/atomserver.
   
   

    cd ~/work
    tar -zxvf atomserver-X.X-install.tar
   
   
   
3. In your shell, export the ATOMSERVER_HOME environment variable. Obviously if you are a Windows person you will need all the BAT equivalents. NOTE: you will probably want to put this in your ~/.bashrc or ~/.bash_profile)
   
   
   

   export ATOMSERVER_HOME=~/work/atomserver
   
   
   
4. Copy the atomserver War (now located at $ATOMSERVER_HOME/webapps) to $CATALINA_HOME/webapps. Renaming it to atomserver.war as you do.
   
   
   

   cp $ATOMSERVER_HOME/webapps/atomserver-X.X.war $CATALINA_HOME/webapps/atomserver.war
   

5. If you do not already have a $CATALINA_HOME/bin/setenv.sh, copy our tomcat-setenv.sh to $CATALINA_HOME/bin/setenv.sh. If you do already have a $CATALINA_HOME/bin/setenv.sh, you will need to merge the contents of our tomcat-setenv.sh with it. Note that the Tomcat startup script (catalina.sh) already calls out to this script ($CATALINA_HOME/bin/setenv.sh) if it is there. This is Tomcat's convenience mechanism for setting up application specific environments. (NOTE: be sure that your new $CATALINA_HOME/bin/setenv.sh has the proper permissions for whatever user is to run Tomcat). The bottom line here is that AtomServer requires that certain variables be passed into it as it starts up, and these required variables are set for you in setenv.sh)

   cp $ATOMSERVER_HOME/bin/tomcat-setenv.sh $CATALINA_HOME/bin/setenv.sh

6. Start Tomcat. ($ $CATALINA_HOME/bin/startup.sh)

NOTES:

• The logs from AtomServer will end up in $ATOMSERVER_HOME/logs
• Make certain that $ATOMSERVER_HOME has the proper permissions for whatever user is to run Tomcat.
• All of your configuration lives outside of AtomServer. This is an extremely important point. You can update AtomServer without touching your configuration specifics.
• I've shown the simplest case above. You may wish to set all of this up using $CATALINA_BASE, in which case the procedure would change somewhat. But the basic steps outlined above will hold.

Our tomcat-setenv.sh looks like this

---

Deploying AtomServer as a Jar within your webapp.

Sometimes you may want to embed AtomServer within your project's webapp, rather than deploy the standard AtomServer War. We make this scenario possible too. In this case, your project would produce a War itself, which most likely deploys an AtomServer servlet within. One important reason to embed AtomServer as a Jar is that IDEs can handle Jars dependencies easily, but War dependencies (e.g. Maven War overlays) really confuse them. (Thus, we use this strategy a lot at our day job.)

Here is how you wire this up with Maven. In your POM, add the following dependency (note the required; <classifier>classes</classifier>)

Next, in your POM, to make things easier, you will want to add a <properties> section.

Finally, in your POM,  you will need to add something like the following to your test plugin, your jetty plugin, and anywhere you need System properties:

And you will need to add something like this to your web.xml:

---

Required Variables to start AtomServer

AtomServer requires certain variables be defined at startup. As you see above, these variables are passed into AtomServer in each of the deployment techniques outlined in this document. In fact, you can see a bash script which sets these variables here.

The variables required by AtomServer at startup are as follows; 

atomserver.env	The AtomServer environment. Tells AtomServer which "env" properties file to load. This variable is critical. This file is located on the Classpath as; "/env/${env}.properties". I.e. if "env=foo", the file should be; ".../env/foo.properties"
atomserver.data.dir	The AtomServer data directory; the directory where Entry files (XML) will be written when using file-based storage. (e.g. $ATOMSERVER_HOME/data)
atomserver.conf.dir	The optional configuration directory. This is another location where AtomServer looks for "env" files, Spring extension files, etc. This directory is put onto the Classpath, including ${atomserver.conf.dir}/classes and all JARs in ${atomserver.conf.dir}/lib.
atomserver.ops.conf.dir	The optional Operations configuration directory. This is another directory where AtomServer looks for "env" files, Spring extension files, etc. It allows a separate location where you can put configuration files that may require specila protection for Operations.
atomserver.home	The root of the atomserver install. In other words, the root of the expanded AtomServer tarball. (e.g. $ATOMSERVER_HOME)
atomserver.port	The HTTP port to use for AtomServer (This variable will eventually be removed.)
atomserver.http.port	The HTTP port to use for AtomServer (e.g. 8080)
atomserver.http.host	The HTTP host to use for AtomServer (e.g. 0.0.0.0)
atomserver.jmxhttp.hostname	The JMX HTTP port to use for AtomServer (e.g. 9080)
atomserver.jmxhttp.hostname	The JMX HTTP host to use for AtomServer (e.g. 0.0.0.0)
atomserver.servlet.context	The base Servlet context (e.g. "atomserver" in http://localhost:8080/atomserver)
atomserver.servlet.mapping	The base Servlet mapping (e.g "v1" in http://localhost:8080/atomserver/v1)
root.loglevel	The root logging level for log4j. (e.g. WARN)
root.appender	The root appender for log4j (should be either StdoutFile or Stdout)
atomserver.loglevel	The logging level for AtomServer. (e.g. INFO)
atomserver.logdir	The directory to log into. (e.g. $ATOMSERVER_HOME/logs)
atomserver.logfilename	The base name for AtomServer log files. (e.g. "atomserver" will result in atomserver.stdout.log, etc.)