/docs/index.txt

  1Silver Lining
  2=============
  3
  4.. contents::
  5
  6.. toctree::
  7
  8    design
  9    terminology
 10    services
 11    appconfig
 12    deploymentconfig
 13    envvariables
 14    devpatterns
 15    management-scripts
 16    php
 17    processes
 18    providers
 19    examples
 20    django-quickstart
 21    disabling-sites
 22    docswanted
 23    todo
 24    comparisons
 25    dns
 26    filelayout
 27    devel-silverlining
 28    license
 29    contributors
 30    Repository <http://bitbucket.org/ianb/silverlining>
 31    Mailing List <http://groups.google.com/group/silverlining-dev>
 32    Continuous Integration Server <http://ci.cloudsilverlining.org>
 33    Presentation on Silver Lining <http://bit.ly/azvW7t>
 34
 35.. comment: not working
 36
 37    Pre-built zip files <http://cloudsilverlining.org/zip/>
 38
 39This is a script and server layout to manage Python-based web
 40applications.  And PHP.
 41
 42Author, license, etc
 43--------------------
 44
 45This is written by `Ian Bicking <http://ianbicking.org>`_; you might
 46`join the list <http://groups.google.com/group/silverlining-dev>`_ or
 47`open a ticket <http://bitbucket.org/ianb/silverlining/issues/>`_, or
 48maybe head on over to FreeNode, ``#silverlining``.  There's a
 49`bitbucket repository <http://bitbucket.org/ianb/silverlining>`_.  It
 50was written with support by `The Open Planning Project
 51<http://openplans.org>`_.
 52
 53It's under the `GPL <license.html>`_, though that **does not** imply
 54anything with respect to the licensing on applications that use this
 55for deployment.  All files in ``silverlining/server-files/support``
 56should be considered to be MIT-licensed (these files actually come
 57close to coexisting with deployed files, though even those don't come
 58very close).
 59
 60.. comment:
 61
 62   Maybe this is predicting pushback unnecessarily... so consider this
 63   a possible but not necessary bit of documentation.  But if you give
 64   me grief about the GPL, consider this the response...
 65
 66   If you have a problem with the GPL for this application you need to
 67   get over yourself.  The GPL isn't viral to your application, and
 68   that's the only reasonable interpretation of the GPL.  I don't care
 69   about what stupid lawyers say about the GPL; if a lawyer is telling
 70   you or your employer scary stories about what the GPL does, your
 71   lawyer is a bad lawyer and I'm not going to work around your
 72   organizational bug.  If you really have a valid problem with *this*
 73   program being under the GPL, then I guess you want to make
 74   proprietary extensions to it, then eh, I'm not really interested.
 75
 76Who Should Use Silver Lining
 77----------------------------
 78
 79Maybe not you!  Silver Lining is not a supported product.  If you want
 80to use Silver Lining, then Silver Lining is not for you.  If you want
 81to help develop Silver Lining, then maybe Silver Lining is for you.
 82If you want to fix problems, provide patches, and collaborate on the
 83project, then great.  Maybe at a later date this will be a more
 84usable, reliable tool; but that time is not right now.
 85
 86To repeat: Silver Lining is for collaborators, not users!
 87
 88What Does It Do?
 89----------------
 90
 91This is a script that:
 92
 931. Can create and destroy virtual servers, using a Cloud service API
 94   (something supported by `libcloud <http://libcloud.org>`_).
 952. Sets up an Ubuntu server to a known configuration.
 963. Deploys Python web applications to these servers.
 97
 98(Also it can deploy PHP applications, maybe other languages in the
 99future.)
100
101You shouldn't concern yourself too much with the server at this
102point.  Instead, let us ask: what does the application look like?
103
104The Application
105---------------
106
107Silver Lining is inspired by Google App Engine in this respect; an
108application is a bunch of files that are uploaded to the server.  You
109don't "build" an application on the server.  To upload or update an
110application, you run::
111
112    $ silver update path/to/app/ myapp.com
113
114This uploads your files, makes sure requests to myapp.com go to your
115new application.  Your application has a file ``app.ini`` (located, in
116this example, in ``path/to/app/app.ini``) which describes the basics
117of the application.
118
119This also sets up any *services* that you need for your application
120(which you have listed in ``app.ini``).  **Services** include any kind
121of persistence your application requires.  This would be a database,
122or even just a location where you can store files (which isn't
123available unless you ask for it).  These services then *inject* their
124configuration into your application though environmental variables.
125So when you start your application you might look for
126``os.environ['CONFIG_PG_DBNAME']`` to see what PostgreSQL database you
127should connect to.  (What each service adds to the environment is
128covered in the `services <services>`_ document.)
129
130You might also ask: what about binary packages?  For instance, `lxml
131<http://codespeak.net/lxml/>`_.  With Silver Lining only *portable*
132files can go in your application directory; typically ``.py`` files,
133templates, and other plain-text data files.  So if you want lxml you
134have to have the Ubuntu package installed; you'd add (to ``app.ini``)
135the configuration ``packages = lxml``.
136
137A lot of this is covered in `application configuration <appconfig>`_.
138
139And what kind of frameworks can you use with Silver Lining?  Anything
140really.  The only real exception is Zope 2, which has strict Python
141version requirements, lots of C extensions, and all sorts of other
142complexities.  `Repoze <http://repoze.org/>`_ will work fine though,
143and a `ZEO
144<http://wiki.zope.org/ZODB/guide/node2.html#SECTION000230000000000000000>`_
145service is easy to imagine (though not yet implemented).
146
147The Server
148----------
149
150The server is setup thusly:
151
152* Ubuntu Lucid 10.04 LTS
153
154* Python 2.6.
155
156* Apache with mod_wsgi.
157
158* But you don't directly interact with either of these.
159
160* Right now the persistence handling is minimal;
161  this is where the most additional support needs to be added to the
162  system (backups, migration, cloning, separating servers, and
163  eventually stuff like replication). Currently there is basic setup for:
164
165  * PostgreSQL with the PostGIS extensions.
166  * CouchDB served locally
167  * MongoDB served locally
168
169* Nothing cron-like has been implemented yet, though probably it will
170  be implemented very similar to App Engine (with internal requests).
171  App setup and migration has to be hand-coded, but can be configured
172  to be run.
173
174* Each app lives at its own domain; per-directory applications are not
175  currently implemented (but would be nice).  Multiple hostnames
176  pointing to a single application is not implemented, but would be
177  easy.  Wildcards require some more thought (simply in terms of
178  Apache configuration).
179
180Provider support
181----------------
182
183This package currently has only been tested with `Rackspace
184<http://www.rackspace.com/cloud/?id=918>`_.  The only specific
185Rackspace extension is the use of "files" on server creation (this is
186part of the node-creation API that uploads files on the newly created
187node/server).  The use of the files extension is minimal at this point
188(just setting up ``/root/.ssh/authorized_keys``), and it is usable
189without that.  If you are signing up for an account by clicking
190through `this affiliate link
191<http://www.rackspace.com/cloud/?id=918>`_ you can throw a few bucks
192my way.
193
194Silver Lining uses `libcloud`_, which is a library abstracting several
195provider APIs.  It should be usable with other providers, but it's
196only been tried with Rackspace, expect bumps with other services.
197
198Language Support
199----------------
200
201There is some experimental support for `PHP <php>`_; it's not
202incredibly graceful, but it has many of the same deployment advantages
203as with Python.
204
205Other languages would also be possible.  Ruby is a prime candidate of
206course, probably using `Passenger <http://www.modrails.com/>`_ instead
207of mod_wsgi.  If I had any clue how Perl was best deployed, it might
208also seem reasonable.  But I (Ian) only have a personal interest in
209the two supported platforms and *maybe* Java.
210
211Installing
212----------
213
214.. comment: broken
215
216 First, grab the newest zip file snapshot from `the zip/ directory </zip/>`_.
217
218 Unpack the zip file, and run ``silver.py``.  You can't move this
219 file out of the directory with the other library files, but you can
220 alias it or something.
221
222Window clients are not supported.  The only way Windows will be supported
223is if someone volunteers to maintain the Windows support.  Individual
224patches won't be accepted until that time -- it would only be a
225disappointment to Windows users to get a half-working and unsupported client.
226
227If you don't want to install from the zip file, you can install Silver
228Lining into a virtualenv environment pretty easily too:
229
230First get `virtualenv <http://virtualenv.openplans.org>`_, which also
231gives you `pip <http://pip.openplans.org>`_.  Also be sure you have
232Mercurial (``hg``) and Subversion (``svn``) installed.  Then run::
233
234    $ virtualenv -p python2.6 silver
235    $ silver/bin/pip install -r http://bitbucket.org/ianb/silverlining/raw/tip/requirements.txt
236
237This installs a bunch of stuff, most importantly
238``silver/bin/silver``.  Your applications will go in a separate
239environment, so you should be sure that ``silver`` works regardless of
240what virtualenv environment is activated.  I recommend::
241
242    $ alias silver="/path/to/silver/bin/silver"
243
244Cloud Server Management
245-----------------------
246
247There's several commands just to manage servers (also called nodes).
248These are really just frontends to what libcloud provides.
249
250Each "node" has a hostname, which is the name of the node, and also
251the hostname setup in ``/etc/hosts``.
252
253``silver list-images``:
254    Lists all the images available (these are starter systems that can
255    be cloned).
256
257``silver list-sizes``:
258    Lists all the sizes (plans) you can get for your server (a
259    combination of RAM/disk and sometimes bandwidth).
260
261``silver create-node``:
262    Creates a new node (aka server).
263
264``silver destroy-node``:
265    Deletes a node. It is advisable to remove the node from
266    ``~/.ssh/known_hosts`` after destroying it to avoid SSH warnings
267    in future.
268
269``silver setup-node``:
270    This takes a bare Ubuntu Lucid system and sets it up.