PageRenderTime 61ms CodeModel.GetById 40ms RepoModel.GetById 0ms app.codeStats 0ms

/docs/index.txt

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