Tailor Documentation. Release 0.1. Derek Stegelman, Garrett Pennington, and Jon Faustman

Transcription

1 Tailor Documentation Release 0.1 Derek Stegelman, Garrett Pennington, and Jon Faustman August 15, 2012

2

3 CONTENTS 1 Quick Start Requirements Installation Authors Core Authors Tailor Decorators Tailor Server API Tailor Command JSON License 11 6 Feature Set 13 i

4 ii

5 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 decorator. CONTENTS 1

6 Tailor Documentation, Release CONTENTS

7 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 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

8 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 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 decorator. Returns a list of the available Fabric commands, including docstrings and required parameters /tailor/api/schema/?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Method: GET 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 : [ ], commands : [ { command : alpha }, 4 Chapter 1. Quick Start

9 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

10 Tailor Documentation, Release Chapter 1. Quick Start

11 CHAPTER TWO AUTHORS 2.1 Core Authors Garrett Derek Stegelman 7

12 Tailor Documentation, Release Chapter 2. Authors

13 CHAPTER THREE TAILOR DECORATORS Using the 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 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) 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 def virtualenv(command): with cd(env.directory): run(env.activate + && + command) 9

14 Tailor Documentation, Release Chapter 3. Tailor Decorators

15 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": " 11

16 Tailor Documentation, Release Chapter 4. Tailor Server API

17 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

18 Tailor Documentation, Release Chapter 5. License

19 CHAPTER SIX FEATURE SET Drop in fabfile Execute decorated functions through a HTTP based API. Key based authentication 15