Introduction

Ramona is runtime supervisor: component of a software product that takes care of smooth start and stop of the solution (including daemonization), of it’s runtime monitoring (logging, unexpected exits, etc.) and of various tasks that are connected with project like continuous integration, unit test automation, documentation builds etc.

Full set of features is described here.

Integration with your project

Assuming you have successfully installed Ramona, you can start integrating it with your project.

You have to provide two files: supervisor launcher and its configuration.

Supervisor launcher

Supervisor launcher is small piece of Python code, that is actually executable by user.

Assuming your project is called foo, you need to create file foo.py with following content (just copy&paste it).

#!/usr/bin/env python
import ramona

class FooConsoleApp(ramona.console_app):
      pass

if __name__ == '__main__':
      app = FooConsoleApp(configuration='./foo.conf')
      app.run()

Make sure that it is marked as executable (e.g. by chmod a+x ./foo.py on UNIX platform).

Note

It is important to use correct version of Python interpreter with Ramona. Some systems happens to have multiple versions installed, so PATH environment variable should be correctly set for relevant user(s) to point to proper Python.

Configuration

You also need to create application-level configuration file which will instruct Ramona what to do.

Create file named foo.conf (actually referenced from foo.py you just created - you are free to change name based on your preferences).

Content of the file is as follows:

[general]
appname=foo

[program:appserver]
command=[command-to-start-your-app]

[command-to-start-your-app] is command that your project uses to start.

You can entry [program:x] section more times - for each ‘long running’ component of your project.

Basic usage

Ramona provides build-in help system.

$ ./foo.py --help
usage: foo.py [-h] [-c CONFIGFILE] [-d] [-s]
              {start,stop,restart,status,help,tail,console,server} ...

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIGFILE, --config CONFIGFILE
                        Specify configuration file(s) to read (this option can
                        be given more times). This will override build-in
                        application level configuration.
  -d, --debug           Enable debug (verbose) output.
  -s, --silent          Enable silent mode of operation (only errors are
                        printed).

subcommands:
  {start,stop,restart,status,help,tail,console,server}
    start               Launch subprocess(es)
    stop                Terminate subprocess(es)
    restart             Restart subprocess(es)
    status              Show status of subprocess(es)
    help                Display help
    tail                Tail log of specified program
    console             Enter interactive console mode
    server              Launch server in the foreground

Start of your application:

$ ./foo.py start

Stop of your application:

$ ./foo.py stop