Commits

Brent Tubbs committed fddf65a

ver 0.3.13

Comments (0)

Files changed (3)

+Overview
+--------
+
+Silk is a Fabric_ based tool for setting up Python WSGI apps on what I like to
+call the SNUG stack:
+
+* Supervisord_ for starting processes and keeping them alive.
+* Nginx_ for proxying between your WSGI app and the big bad web.
+* Ubuntu_ as the OS of choice, enabling resolution of system dependencies with
+  apt.  Debian might work as well but hasn't been tested.
+* Gunicorn_ for serving your WSGI app.
+
+(I suppose it could also be the GUNS stack but that sounds far less friendly.)
+
+Key Features
+~~~~~~~~~~~~
+
+* Deploy your site to one or more servers with a single command ('silk push').
+* Automatic configuration of Nginx, Supervisord, and Gunicorn to get your site running.
+* Isolation of each site into a separate Virtualenv_
+* Support for differing app config depending on which role you deploy to (a 
+  different DB in staging than production, for example).
+
+Installation
+~~~~~~~~~~~~
+
+Use pip::
+
+    pip install silk-deployment
+
+You can also install the current development version straight from bitbucket::
+
+    pip install hg+http://bits.btubbs.com/silk-deployment#egg=silk-deployment
+
+Commands
+--------
+
+(Almost) all of the commands below require that you specify a role name, like
+'silk dosomething -R dev'.
+
+Commands can generally be run from the site root directory or any subdirectory
+of it.
+
+push
+~~~~
+
+::
+
+    silk push -R rolename
+
+This command is the main reason for Silk's existence. It does the work required
+to get your app running on a host (or set of hosts) given the configuration
+specified in site.yaml and the selected role .yaml file.  'push' does the
+following:
+
+1. SSHes to the remote server(s) specified in the role config.
+2. Copies the site from your local machine to a temporary directory on the
+   remote server.
+3. Creates a virtualenv for the site.
+4. Installs python dependencies into the virtualenv.
+5. Writes config file includes for nginx and supervisord.
+6. Writes a supervisord config for the site and starts it up.
+7. Makes a request to the homepage to ensure the site is running.
+8. Tells nginx to route traffic to the new instance instead of the old one.
+
+run
+~~~
+
+::
+
+    silk run -R rolename
+
+This command runs the site from the local machine, on port 8000.  (Nothing is
+pushed of copied.)  Static directories listed in the *static_dirs* section of
+site.yaml will also be served.  (CherryPy is used for this magic.)
+
+skel
+~~~~
+
+::
+
+    silk skel sitename
+
+Creates a directory with a basic Silk file and directory structure.
+
+Layout
+------
+
+A silk-enabled project should be layed out something like this::
+
+  mysite.com
+  ├── deps.yaml
+  ├── fabfile.py
+  ├── membrane.py
+  ├── roles
+  │   ├── dev.yaml
+  │   ├── staging.yaml
+  │   └── production.yaml
+  ├── site.yaml
+  └── my-django-project
+
+Some of those files/folders are required, other are optional:
+
+Required
+~~~~~~~~
+
+1. site.yaml - This is the main config file (comparable to app.yaml in Google
+   App Engine)
+2. deps.yaml - Lists Python packages, Ubuntu apt packages, and apt build 
+   dependencies that need to be installed on the server running your site.
+3. roles/\*.yaml - One or more 'role' files that contain the config to be 
+   passed into your app depending on the deployment context.
+
+All of the required files will be created for you with the 'silk skel' command.
+
+Optional
+~~~~~~~~
+
+1. membrane.py - For Django projects it's nice to have a little shim to expose
+   the project as a WSGI app.  I like to call mine membrane.py.  You can use 
+   whatever you like, or nothing at all, depending on your setup.
+2. my-django-project - Silk isn't restricted to Django; any valid WSGI app on 
+   your Python path should be servable.  But for Django projects I think it 
+   makes sense to stick them right there.
+3. fabfile.py - A Fabric_-compatible fabfile that imports Silk's Fabric 
+   functions.  This is where you can customize Silk's 'push' function by
+   wrapping it with your own (I do this to run Django's "collectstatic" on
+   push), or add in your own Fabric tasks.
+
+.. _Supervisord: http://supervisord.org/
+.. _Nginx: http://nginx.org/
+.. _Ubuntu: http://www.ubuntu.com/
+.. _Gunicorn: http://gunicorn.org/
+.. _Fabric: http://docs.fabfile.org/
+.. _Virtualenv: http://virtualenv.openplans.org/

README.rst

-Overview
---------
-
-Silk is a Fabric_ based tool for setting up Python WSGI apps on what I like to
-call the SNUG stack:
-
-* Supervisord_ for starting processes and keeping them alive.
-* Nginx_ for proxying between your WSGI app and the big bad web.
-* Ubuntu_ as the OS of choice, enabling resolution of system dependencies with
-  apt.  Debian might work as well but hasn't been tested.
-* Gunicorn_ for serving your WSGI app.
-
-(I suppose it could also be the GUNS stack but that sounds far less friendly.)
-
-Key Features
-~~~~~~~~~~~~
-
-* Deploy your site to one or more servers with a single command ('silk push').
-* Automatic configuration of Nginx, Supervisord, and Gunicorn to get your site running.
-* Isolation of each site into a separate Virtualenv_
-* Support for differing app config depending on which role you deploy to (a 
-  different DB in staging than production, for example).
-
-Installation
-~~~~~~~~~~~~
-
-Use pip::
-
-    pip install silk-deployment
-
-You can also install the current development version straight from bitbucket::
-
-    pip install hg+http://bits.btubbs.com/silk-deployment#egg=silk-deployment
-
-Commands
---------
-
-(Almost) all of the commands below require that you specify a role name, like
-'silk dosomething -R dev'.
-
-Commands can generally be run from the site root directory or any subdirectory
-of it.
-
-push
-~~~~
-
-::
-
-    silk push -R rolename
-
-This command is the main reason for Silk's existence. It does the work required
-to get your app running on a host (or set of hosts) given the configuration
-specified in site.yaml and the selected role .yaml file.  'push' does the
-following:
-
-1. SSHes to the remote server(s) specified in the role config.
-2. Creates a zipped up rollback archive of the old site if there's one
-   there already.
-3. Creates a virtualenv for the site.
-4. Installs apt and python dependencies.
-5. Copies the site from your local machine to a temporary directory on the
-   remote server.
-6. Writes config file includes for nginx and supervisord.
-7. Moves your code from the temp dir into its production location
-   (/srv/<sitename> by default).
-8. Tells nginx and supervisord to reload their configs.
-
-
-rollback
-~~~~~~~~
-
-::
-
-    silk rollback -R rolename
-
-This command is for when you have those 'OMG I BROKE THE SITE' moments. It will
-SSH to the push_hosts specified in your role file and restore the most recent
-archive of the site. Silk keeps 3 rollback copies of your site, so you could
-potentially run 'silk rollback' 3 times to go back to the state from 3
-deployments ago.
-
-run
-~~~
-
-::
-
-    silk run -R rolename
-
-This command runs the site from the local machine, on port 8000.  (Nothing is
-pushed of copied.)  Static directories listed in the *static_dirs* section of
-site.yaml will also be served.  (CherryPy is used for this magic.)
-
-server_setup
-~~~~~~~~~~~~
-
-::
-
-    silk server_setup -R rolename
-
-When you get a shiny new server with that fresh Ubuntu smell, it needs just a
-tiny bit of setup before it will know how to serve silk-deployed sites.  This
-command does that.  It installs nginx and supervisord, and gives each of them a
-wildcard include in their configs for loading from /srv/<sitename>/conf.
-
-deps
-~~~~
-
-::
-
-    silk deps
-
-This command wraps 'pip install' to install all of the python packages listed
-in deps.yaml into your local python environment.  It's handy for grabbing all
-the dependencies when you're working with a new virtualenv on an existing
-project.
-
-skel
-~~~~
-
-::
-
-    silk skel sitename
-
-Creates a directory with a basic Silk file and directory structure.
-
-Layout
-------
-
-A silk-enabled project should be layed out something like this::
-
-  mysite.com
-  ├── deps.yaml
-  ├── fabfile.py
-  ├── membrane.py
-  ├── roles
-  │   ├── dev.yaml
-  │   ├── staging.yaml
-  │   └── production.yaml
-  ├── site.yaml
-  └── my-django-project
-
-Some of those files/folders are required, other are optional:
-
-Required
-~~~~~~~~
-
-1. site.yaml - This is the main config file (comparable to app.yaml in Google
-   App Engine)
-2. deps.yaml - Lists Python packages, Ubuntu apt packages, and apt build 
-   dependencies that need to be installed on the server running your site.
-3. fabfile.py - A Fabric_-compatible fabfile that imports Silk's Fabric 
-   functions.
-4. roles/\*.yaml - One or more 'role' files that contain the config to be 
-   passed into your app depending on the deployment context.
-
-All of the required files will be created for you with the 'silk skel' command.
-
-Optional
-~~~~~~~~
-
-1. membrane.py - For Django projects it's nice to have a little shim to expose
-   the project as a WSGI app.  I like to call mine membrane.py.  You can use 
-   whatever you like, or nothing at all, depending on your setup.
-2. my-django-project - Silk isn't restricted to Django; any valid WSGI app on 
-   your Python path should be servable.  But for Django projects I think it 
-   makes sense to stick them right there.
-
-.. _Supervisord: http://supervisord.org/
-.. _Nginx: http://nginx.org/
-.. _Ubuntu: http://www.ubuntu.com/
-.. _Gunicorn: http://gunicorn.org/
-.. _Fabric: http://docs.fabfile.org/
-.. _Virtualenv: http://virtualenv.openplans.org/
 
 setup(
     name='silk-deployment',
-    version='0.3.12',
+    version='0.3.13',
     author='Brent Tubbs',
     author_email='brent.tubbs@gmail.com',
 	packages=find_packages(),
     url='http://bits.btubbs.com/silk-deployment',
     license='LICENSE.txt',
     description='A Fabric-based tool for deploying WSGI apps on an Ubuntu/Nginx/Supervisord/Gunicorn stack.',
-    #long_description=open('README.rst').read(),
+    long_description=open('README').read(),
 )
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.