Package: gilliam-cli
# The Gilliam Command-Line InterfaceGilliam is a software platform for building and running distributedsystems.This is the command-line tool that is used to control services runningon the Gilliam platform.## InstallationInstall using pip (preferably in a virtualenv) straight from therepository:$ pip install git+https://github.com/gilliam/gilliam-cli.gitThat's it. The command is called `gilliam`.# Quick IntroFirst a few words about Gilliam application model: A *service* is apiece of code that runs on the platform.  It can be some businesslogic, a cache or a database.  Services are grouped together into a*formation*.  Code and configuration in the form of environmentvariables are merged together into a *release*.  *Instances* of aservice can be created from a release.  Everything live in a *stage*,which is another word for a gilliam installation.In this quick into we'll use a small python example to showcase someof the commands of the client.  First, we need to clone the examplecode:$ git clone git+https://github.com/gilliam/python-example.git$ cd python-exampleLets take a look at the `gilliam.yml` file:processes:www:script: python web.pyports: [80]A `gilliam.yml` file specifies a set of services that the formationneed to expose functionality.  In file above contains just a processcalled `www`.  The `script` tells us that when the service is startedthe command `python web.py` should be executed.  `ports` specifiesports on which the service can receive incoming requests.Gilliam comes with a whole set of different service types. The typefor a service can always be specified with a `type` field.  But youcan also let it to Gilliam to figure out the type; the type will thenbe deduced from the service name and its definition.Back to the example.To create a formation for the example issue the following command:$ gilliam --stage myapp-prod create python-exampleWe specify `--stage myapp-prod` to tell the client to create theformation in the `myapp-prod` stage (the production environment for myapplication).*Note*: This quick into does not take into consideration how the stageis created.Next step is to build and deploy:$ gilliam deploystart building service 'www' ...|        Python app detected| -----> No runtime.txt provided; assuming python-2.7.4....|        Successfully installed Flask Werkzeug Jinja2 markupsafe|        Cleaning up...|        Cleaning up cachesrelease 1When done, a new release has been created. You can see it if you do a`gilliam-cli releases`:$ gilliam releasesname      author          message--------- --------------- ----------------------------------------1         jrydberg        NoneGilliam allows heterogeneous set ups where you have instances frommultiple releases running at the same time.  This allows you to buildsophisticated build pipelines with canary tests.But right now, nothing is running, since we have not scaled therelease.  So lets do that:$ gilliam scale -r1 www=1$This will create an instance of the `www` service and dispatch it toone of the executors. Run `gilliam-cli ps` to inspect instances:$ gilliam-cli psname                                release state----------------------------------- ------- ---------www.BHCrBMebfG4oZUgix95chH          1       runningTo be able to access the service from the outside, we need to set upa route:$ gilliam-cli route /example/ www.example.serviceroute 5h7Zf9P3oDGiUpF3opWDzP createdSo what does that mean?  It means that `/example/` on the router,regardless of domain, will route requests to the example service.Routes can be listed by issuing `routes` command:$ gilliam-cli routename                   domain               path                 target---------------------- -------------------- -------------------- -------------------------5h7Zf9P3oDGiUpF3opWDzP                      /example/            http://www.example.service# Basic Commands## Creating a FormationThe first command you will issue.  It needs to be issued from your"project dir", which is the directory where your `gilliam.yml` filelive.  Normally this is the root directory of your project.$ gilliam --stage prod create name-of-formationThe `--stage` option tells gilliam in what installation the formationshould be created.  Here's it's the production environment.## DeployingTo build your project and release it just issue the `deploy` command:$ gilliam deploy...## Scaling a ReleaseScaling a release means to increase or decrease the number ofinstances of that release.(FIXME: default to last release, or to <all releases> somehow?)## RoutingGilliam has a front-end HTTP router that takes request and forwardsthem to a service for process.The command `route` takes two arguments, the *route* and the *target*.$ gilliam route /example/ www.example.serviceThe route can contain a domain name that needs to be matched:$ gilliam route api.myapp.com/example/ www.example.serviceThe route argument accepts variable matching using the `{var}` syntax,like this:$ gilliam route /user/{user} www.user.service/{user}If you want to specify a specific format for the variable, do so aftera colon, like this: `{name:REGEX}`.  For example `{rest:.*?}` willmatch the rest of the line, which can be useful if you want to sendeverything to a specific service.$ gilliam route /user/{rest:.*?} www.user.service/{rest}Note that variable matching is also possible on the domain:$ gilliam route {acct}.api.myapp.com/user/{rest:.*?} api.user.service/{acct}/{rest}Or in the formation name:$ gilliam route {acct}.api.myapp.com:/user/{rest:.*?} api.user-{acct}.service/{rest}By not specifying any arguments all existing routes will be listed:$ gilliam routesname                   domain               path                 target---------------------- -------------------- -------------------- -------------------------5h7Zf9P3oDGiUpF3opWDzP                      /example/            http://www.example.serviceDeleting a formation is done using the `-d` option:$ gilliam route -d <route-name>## Building a Release...