Tailor Documentation Release 0.1 Derek Stegelman, Garrett Pennington, and Jon Faustman August 15, 2012
CONTENTS 1 Quick Start 3 1.1 Requirements............................................... 3 1.2 Installation................................................ 3 2 Authors 5 2.1 Core Authors............................................... 5 3 Tailor Decorators 7 3.1 @tailored................................................. 7 3.2 @dependency.............................................. 7 4 Tailor Server API 9 4.1 Tailor Command JSON......................................... 9 5 License 11 6 Feature Set 13 i
ii
Tailor Documentation, Release 0.1 Tailor is a Python (Django) application designed to take your fabric commands, and make them executable from an API. Tailor is built with modularity in mind by binding explicitly to the Fabric file you supply. Fabric commands can be made accessible to the web API by adding the @tailored decorator. CONTENTS 1
Tailor Documentation, Release 0.1 2 CONTENTS
CHAPTER ONE QUICK START 1.1 Requirements Django 1.3.x or greater Fabric 1.2 Installation To install Tailor simply install via pip: pip install tailor 1.2.1 Client Installation Add application to installed apps: INSTALLED_APPS += ( tailor.client, ) Add tailor.urls to your url conf: urlpatterns = patterns(, ) url(r ^tailor/, include( tailor.client.urls )), Add TAILOR_FABFILE_PATH, a path to your fabfile, to your Django settings file.: TAILOR_FABFILE_PATH = "/path/to/your/fabfile.py" Add TAILOR_API_KEYS, a dictionary of accepted keys, to your Django settings file.: TAILOR_API_KEYS = { dashboard : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, hubot : YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY, arduinio : ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ, } 3
Tailor Documentation, Release 0.1 Note: Tailor includes a simple alphanumeric key generator. from tailor import keygen then run keygen.generate(32) In your fabfile, from tailor.client.decorators import tailored. To make Fabric commands available to Tailor, add the @tailored decorator to any Fabric function. For functions that may be used by other fabric tasks, but shouldn t be directly callable via the api, add the @dependency decorator. Returns a list of the available Fabric commands, including docstrings and required parameters /tailor/api/schema/?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Method: GET 1.2.2 Servent Installation Add application to installed apps: INSTALLED_APPS += ( tailor.servent, ) Add tailor.urls to your url conf: urlpatterns = patterns(, ) url(r ^tailor/, include( tailor.servent.urls )), Using the Admin If you don t want to make your own custom Tailor client, you can use the admin. Add entries to the Project model including the location of a tailor schema and a valid Tailor api key. Execute commands from with the change form page in the admin. Rolling your own Client You can make any number of clients with any language, device, or method. Simply post JSON to a tailor fab location with the following information. If you project is recorded in the Tailor Project model, you can include the id in the Tailor fab api. Otherwise, omit an id and provide a schema_url and an api_key Run Fabric commands URL: /your_tailor_url_path/api/v1/fab/<id> Method: POST POST DATA (for a remote host): { hosts : [ http://server1.example.com, http://server2.example.com, http://server3.example.com ], commands : [ { command : alpha }, 4 Chapter 1. Quick Start
Tailor Documentation, Release 0.1 } { command : deploy, parameters : [ 0.96, ] } ], apikey : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX POST DATA (for the same host): { } hosts : self, commands : [ { command : production }, { command : restart_apache } ] 1.2. Installation 5
Tailor Documentation, Release 0.1 6 Chapter 1. Quick Start
CHAPTER TWO AUTHORS 2.1 Core Authors Garrett Pennington @gpennington Derek Stegelman - @dstegelman 7
Tailor Documentation, Release 0.1 8 Chapter 2. Authors
CHAPTER THREE TAILOR DECORATORS 3.1 @tailored Using the decorator @tailored on a fabric method will set an attribute that allows the method to be accessible via the tailor API. Example: from tailor.client.decorators import tailored @tailored def collect_static(): """ Collect static files, run before comitting call alpha or production first """ virtualenv("python manage.py collectstatic --noinput --settings=settings.%s" % env.branch) 3.2 @dependency The dependency decorator is used when Tailor needs access to the fabric command for the API, but you don t want to be able to access the method directly. Example: from tailor.client.decorators import dependency @dependency def virtualenv(command): with cd(env.directory): run(env.activate + && + command) 9
Tailor Documentation, Release 0.1 10 Chapter 3. Tailor Decorators
CHAPTER FOUR TAILOR SERVER API 4.1 Tailor Command JSON { } "hosts": [ "server1.example.com" ], "commands": [ { "command": "make_release", "params": [ { "name": "tag", "value": "1.0" }, { "name": "message", "value": "a new tag" } ] }, { "command": "alpha", "params": [] } ], "api_key": "sdfsdlkoweiu209823f4980fsadnfbqamck3i", "schema_url": "http://localhost:8001/tailor/api/v1/schema/" 11
Tailor Documentation, Release 0.1 12 Chapter 4. Tailor Server API
CHAPTER FIVE LICENSE Copyright (c) 2012 Garrett Pennington, Derek Stegelmen, Jon Faustman Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software ), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PAR- TICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 13
Tailor Documentation, Release 0.1 14 Chapter 5. License
CHAPTER SIX FEATURE SET Drop in fabfile Execute decorated functions through a HTTP based API. Key based authentication 15