/docs/index.txt
Plain Text | 270 lines | 208 code | 62 blank | 0 comment | 0 complexity | 202654d0527cad6cff9f1630371b68a9 MD5 | raw file
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.