Dad Server API
The main interface point is the Dad Server. This is where you can interact with applications. All the interactions are done via HTTP.
The config format is a typical ini style. We use the ConfigParser object in Python to do the parsing of the config file. The configuration format is used to start up the dad process. The dad process allows interactions with the child processes via a simple HTTP API.
Here is an example of a config file with the basic supported functionality:
[my-app] command = /usr/bin/run-my-server.sh instances = 1 MY_DB_URI = postgres://localhost:9987
The 'my-app' section provides the command to run the application. It will be provided a HOST and PORT via environment variables (env vars). It should expect to get configuration via env vars. This means that any configuration should be provided during deployment.
Env Var Configuration
In example above it can be assume that the 'run-my-server' command is a shell script. The shell script might be something like:
#!/bin/bash python -m mywebapp.run -h $HOST -p $PORT --dburi=$MY_DB_URI
In this scenario we've passed the host, port and dburi as command line arguments but a better design is to look for the HOST and PORT from the environment variables.
Env Var Replacement
Applications are not run in a shell, yet dad will try to replace any env vars provided in the commands when possible. If the env var does not exist it the value will not be changed.
For example, if you wanted to use a directory in the sandbox for storing database files, you could do so. Here is an example with MongoDB:
[mongod] command = mongod --dbpath "$PWD/data/db" --port $PORT PORT = 27017
The "PWD" path is provided by default and is the sandbox directory. Also, you can see that we provided our own "PORT" env var. This will override the starting port provided by the system.
NOTE: By providing a "PORT" env var, you are responsible for dealing with any conflicts between processes.
Interacting with Processes
A dad service should provide basic process management as well as added functionality described by the configuration for the process. The basic process management features are:
- Stop (term/kill)
The start of the application is when the main command is run in the application's sandbox directory.
The start command can be provided configuration information in its initial config. Any key/value pair will be added as env vars. For example:
[foo] command = run-server DB_URI = mongodb://dbserver:27017
The process then can access the 'DB_URI' as an env var.
Stopping a process is a matter of issuing a SIGTERM signal to the process. If the process does not stop, you MAY send a SIGKILL signal to the process.
Restarting a process involves sending it a SIGTERM signal, waiting for it to exit and then running the start command again. You can also specify when restarting some parameters.
Dad supports recieving stream from stdout for the process. This stream is not stateful and acts like the 'tail' command.
A custom interaction is a command that can be configured to run. A good example would be running a test suite or performing a data migration/clean up script.
These commands must be available in the same way the start command is available. They are run in the same sandbox directory and uses the same permissions and env vars.
Here is an example of configuring a custom interaction point.
[foo] command = run-foo DB_URI = mongodb://localhost:27017 [foo:config] migrate = run-migration http://migration-resources/latest
The configuration of a running dad server can be changed while it is running. The config will be saved and versioned after every change.