Commits

Brent Tubbs  committed 015eea8

more README work

  • Participants
  • Parent commits 6f64505

Comments (0)

Files changed (2)

 Copyright (c) 2010, YouGov
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
 
-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-Neither the name of YouGov nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Redistributions of source code must retain the above copyright notice, this 
+list of conditions and the following disclaimer.
 
+Redistributions in binary form must reproduce the above copyright notice, 
+this list of conditions and the following disclaimer in the documentation 
+and/or other materials provided with the distribution.
+Neither the name of YouGov nor the names of its contributors may be used to 
+endorse or promote products derived from this software without specific prior
+written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+POSSIBILITY OF SUCH DAMAGE.
+
  * 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).
- * 
+ * 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
 ------