Source

Dad / docs / apis.rst

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.

Configuration Format

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:

  1. Start
  2. Stop (term/kill)
  3. Restart
  4. Tail

Start

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.

Stop

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.

Restart

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.

Tail

Dad supports recieving stream from stdout for the process. This stream is not stateful and acts like the 'tail' command.

Custom Interactions

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

Configuration Changes

The configuration of a running dad server can be changed while it is running. The config will be saved and versioned after every change.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.