Commits

Anonymous committed 016efef

Updating docs

Comments (0)

Files changed (2)

 2. Provide a simple container for creating more complex production
    environments
 
+History
+=======
+
 When writing code, the process of running tests is rarely
 simple. Often time supporting services need to be setup and
 configured. The services can be complicated to set up and
 maintain. The result is that finding consistently between a
-development environment and production is very difficult. 
+development environment and production is very difficult.
 
 Dad aims to reverse the process by providing a means of configuring
 and maintaining a local production environment, defining the sandbox
 where an application runs and allow controlling those services through
-convenient APIs. 
+convenient APIs.
 
 Dad does not maintain physical hardware or provide any support for
-doing operating system type tasks. What it does do is provide hooks
-for setting up a production system in terms of creating a sandbox for
-applications to run.
+doing operating system type tasks. What it does do is provide a simple
+means for orchestrating services and asking those services to perform
+operations in a specified sandbox environment.
 
-Alpha!!!
-========
+Beta
+====
 
-Dad is alpha software... If even that. It is really an experiment in
+Dad is beta software. It started as an experiment in
 a different conceptual model for development. There is a difficult
 problem of finding agreement between applications for things like
-testing. Dad avoids this problem by providing hooks vs. an API. This
-may be a bad idea. 
+testing. Dad avoids this problem by focusing on processes and letting
+those who setup and deploy the environment consider the larger picture
+(including security).
 
-In either case though, apps within a system should really all support
-similar ways of testing and doing specialized functions in a way that
-allows consistency throughout. This is important b/c it means there
-are not organizational questions when developing in an app that is
-unfamiliar. 
+Installation
+============
 
+To install Dad get the source and change into the directory where it
+is located. Then install it with: ::
 
+  $ python setup.py install
+
+Or if you will be changing code: ::
+
+  $ python setup.py develop
+
+Running Dad
+===========
+
+Dad can be started with the dad.web command. It is a good idea to
+start with a simple config as well. In the configs directory there is
+an example that will start up a simple Python web server serving
+static files. ::
+
+  [simpleweb]
+  command = python -m SimpleHTTPServer $PORT
+  PORT=8000
+
+You can then start the server using this config: ::
+
+  $ DAD_CONFIG=configs/simple.conf dad.web
+
+This will start the dad server and a simple web server that will serve
+static applications. 
+
+The application is run from within it sandbox. You'll notice after
+running the server once that a new 'dad_sandboxes' directory was
+created. Inside that directory you should also find a 'simpleweb'
+directory. This directory is your sandbox directory for your
+application. To test this, you can add a file and see if you can
+access it via the running server. ::
+
+  $ echo 'Hello World!' > dad_sandboxes/simpleweb/hello.txt
+  $ DAD_CONFIG=configs/simple.conf dad.web
+
+Then in your web browser go to http://localhost:8000/hello.txt and see
+if you see "Hello World!".
+
+For more info what is possible in the configuration file check out the
+docs directory.
+
 Configuration Format
 ====================
 
-Here is an example of a config file with all the supported
+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
 
   #!/bin/bash
   
-  export $MY_DB_URI=postgres://localhost:9987
-  
-  python -m mywebapp.run -h $HOST -p $PORT
+  python -m mywebapp.run -h $HOST -p $PORT --dburi=$MY_DB_URI
 
-In this scenario we've passed the host and port as command line
+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.
 
 
 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 a port provided by the system. 
+var. This will override the starting port provided by the system. 
 
-NOTE: By providing a "PORT" env var, you restrict that app to only one
-instance. This is necessary in order to avoid collisions.
+NOTE: By providing a "PORT" env var, you are responsible for dealing
+with any conflicts between processes. 
 
 
 Interacting with Processes
 
  1. Start 
  2. Stop (term/kill)
- 3. Restart (graceful)
+ 3. Restart
  4. Tail
 
 Start
 -----
 
-The start of the application is the running of the command in a
-directory dedicated to the application. The directoy MAY be used for
-writing temporary files but those file will be removed upon a stop or
-restart of the process. In order to keep the same directory and still
-restart the process a "graceful" restart can be requested in which
-case it will use the same the environment. If for some reason the
-graceful restart fails, the fallback is the same as a typical
-restart. 
+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
 it to exit and then running the start command again. You can also
 specify when restarting some parameters.
 
-Hard Restart
-~~~~~~~~~~~~
-
-A hard restart is when after issuing the SIGTERM to the process it
-does not stop on its own. The default means of identifying this
-situation is a simple timeout. Some other scenarios can be
-configured such as waiting for a file handle to change or accessing a
-known URL for a certain response.
-
-Here is how to configure a check before issuing a SIGKILL. ::
-
-  [foo]
-  command = run-foo
-
-  [foo:config]
-  restart_test = verify-foo-shutdown
-
-The 'restart_test' configuration parameter defines a process to run
-that will perform any tests to ensure the process is stopped
-safely. In the case where both processes are not responding, sending a
-stop command with a SIGKILL will kill both the initial process and its
-'restart_test' process.
-
-Graceful Restart
-~~~~~~~~~~~~~~~~
-
-A graceful restart acts just like a normal restart with the single
-difference being that the same working directory is guaranteed to
-exist when the application comes back up.
-
 Tail
 ----
 
 good example would be running a test suite or performing a data
 migration/clean up script. 
 
-These commands are run in the same working directory as the
-application using the same permissions and env vars. 
+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. ::