Super

From Mugshot Developer Wiki

Jump to: navigation, search

There are 4 different processes making up the Mugshot server, each requiring their own configuration and babysitting.

Super is a set of Python scripts that keep track of these processes, both in production and when you're running a local test instance. Super can create a Mugshot instance from scratch (initializing the database, etc.); can push new builds and changes into said instance; and can start and stop the processes in the instance.

Super is controlled by a config file. The configuration defaults are in the file super/base.conf in Subversion. The defaults are for a test/debug instance deployed to ~/dhdeploy and configured by the file ~/.super.conf

[edit]

Usage of Super

The usage of super is: 

./super [--conf=FILENAME] ACTION SERVICES

ACTION is one of:

build
create or recreate the deployment tree for the service
init
create the deployment tree for the service, from scratch, destroying any data.
start
start the service
status
print out the status of the service
stop
stop the service
restart
stop, then start the service
reload
update the configuration and/or software of the service. This may involve a 'build' or 'restart', but if super knows how to do the update more cheaply, it will do it that way.
console
open a console (for database services)
nuke
destroy all data irrevocably (for database services)

SERVICES can either be the name of one or more services, or it can be the special value all. Current services are:

  • mysql
  • jboss
  • jive
  • imbot

If --conf isn't specified, then super looks for a ~/.super.conf. The specified configuration is merged on top of the default configuration in super/base.conf; if no conf file is specified or found, then the default configuration will be used unchanged.

[edit]

Configuring Super for a user

A simple ~/.super.conf might look like: 

(FIXME this is very outdated)
<superconf>
    <parameter name="baseport">42000</parameter>
    <parameter name="mysqlhost">database.dumbhippo.com</parameter>
    <parameter name="mysqlport">4413</parameter>

    <service name="jboss">
         <parameter name="jbossdir">
    </service>
 
    <service name="mysql" enabled="no"/>
</superconf>

This sets the base port relative to which all ports for our local services will be located by default. Then it overrides the values of several default parameters to specify where the MySQL database will be found.

Then we have sections specific to particular services, we set a parameter to say where the JBoss distribution can be found and we disable the mysql service.

[edit]

The default configuration of super

A basic principle of Super is that it is as declarative as possible, but no more. Super is written in Python. Most of the service functionality is defined in the class dumbhippo.super.BaseService, and based on what is found in the config file. But the services can derive from this base class and can override how particular actions work. 

<superconf>
    <parameter name="basedir">/srv/dumbhippo</parameter>
    <parameter name="baseport">21000</parameter>
    <parameter name="svndir">$superdir/..</parameter>
    
    <service name="jboss"
             class="dumbhippo.super.JBossService">
       <parameter name="jbossdir">/usr/lib/jboss-4.0.3RC2/</parameter>
       <parameter name="targetdir>$basedir/jboss</parameter>
       <parameter name="rmiport">$((baseport+13))</parameter>
 
       <merge src="$jbossdir/server/default"
              target="$targetdir"
              exclude="$superdir/jboss.exclude"/>
       <merge src="$superdir/jboss-config"
              target="$targetdir"
              expand="yes"/>
       <merge src="$svndir/web/target/dumbhippo-web.war"
              target="$targetdir/deploy/dumbhippo-web.war"
              hot="yes"/>
  
       <stop-comamnd>$jbossdir/bin/shutdown.sh localhost $rmiport</stop-command>
    </service>
</superconf>

All sorts of things things to note in the above:

  • Once we define parameters, we can substitute them into attributes and values. Expansion is lazy and global, in the style of Make ... we load the entire base configuration, merge in the entire user configuration, and only when a value is referenced are parameters expanded.
  • Parameters are scoped - one defined within a <server/> tag is only visible in that server tag.
  • We support at least simple bash-style arithmetic expansion. (Well, only $((varname+<n>)) for now)
  • $superdir is a predefined parameter, which is the directory in which the super script is located.
  • The <merge/> element is a declarative way of defining the server deployment tree. We basically, simply merge together a bunch of sources directories and files, but there are various refinements we can make:
    • 'exclude' gives a rsync-style list of files to exclude
    • 'expand' says to expand paramaters when merging, the parameters are written like @rmiport@
    • 'hot' is a hint that during 'reload' we can just copy the file over, and don't need to stop and restart the server.
  • <stop-command/> configures the BaseService implementation of the 'stop' action.
Retrieved from "http://developer.mugshot.org/wiki/Super"
Personal tools