README

== About ==
Minister is a web-server that matches the needs of modern web development. 
Rarely do we have simple html files sitting in directories any more.  Today,
applications are complex and dynamic yet our servers still adhere to old
expectations and assumptions.

Minister has four goals:
 * Make application deployment extremely simple.
   We achieve this by treating applications as "services", each can be
   configured easily with a service.json file found in the base directory of
   the app.  Apps can also be specified merely by pointing to a resource such
   as a url of a tarball, a git or hg repository, or an rsyncable directory.
 * The server should be monitoring your apps.
   Minister will monitor your application processes, if one goes down it will
   restart it.  Other monitoring is planned for the future like cpu usage,
   health monitoring, email alerts when things get out of whack, and even
   dynamically spinning up new processes to handle load.
 * Separate applications into distinct environments.
   Because applications are each run in their own process (and sometimes 
   multiple processes), they can exist in their own runtime environments. This
   allows Ruby programs to work flawlessly next to PHP, or Python interpreters
   in separate virtualenvs.
 * Provide a web-resource for the server itself.
   The Minister Administration service allows the user to see what services 
   are currently running, and what their state is.  You will also be able to
   bring them up and down, modify details of their configuration right in the
   admin.  It will also provides a REST interface for doing the same.
   Note: This feature is not yet complete, you can see the status of the
   services, but not interact with them yet.


== Running While In Development ==
   You can install minister and run it like normal:
   > minister
   
   That will assume your minister repository is at ~/.minister
   Or you can specify with:
   > minister -p /path/to/repo
   
   Instead of having to install, you can also, from the minister source root:
   > ./dev -p tests/repo
   
   That will start it up pointing to the repository in tests/repo.
 
   There is also a debug mode, that currently merely outputs some info when
   returning 404 or 500 errors, run with -d:
   > ./dev -p tests/repo -d
   
   Also, you can run verbose, which will output anything that would go to
   the logs also to the terminal:
   > ./dev -p tests/repo -d -v


== Brief Architecture ==
Minister starts up by running the function "run()" in manager.py, which sets
up the optparser, creates a Manager() instance, and calls its "serve()"
method.  Which has the manager gather and account for services, and then start
its front-end listener on port 80, if run as root, or 8000 otherwise.

The manager acts as a reverse proxy, static file server, and handler of the
various back-end services. From a high-level perspective "Services" are
running processes that provide some sort of resource, for instance a
fastcgi-php process or a python application serving a wsgi application, or
even a memcachedb server. The manager takes requests, figures out who gets the
request based on the requested URL or site name, and then proxies them to
these services. The manager is also entrusted with starting these services,
and even keeping their source up to date.

The manager doesn't directly work with services, it actually works with
service *Tokens*, as defined by the *tokens.Token* class. Generally the user
doesn't need to bother with the distinction, but tokens handle deployment,
various settings, and importantly, the updating of the service source.  By
setting the "source" of a service to be an rsyncable directory, a git or hg
repository, or some remote web tarball, the token will handle the downloading
and installing of that source into the service directory.  Services can be 
configured by making changes to the token that is saved to the config.json
in the manager repository.  Or by altering the service.json within the 
service's root.