/docs/services.txt
Plain Text | 259 lines | 176 code | 83 blank | 0 comment | 0 complexity | 2b04b11b2093d7e158b4515493a773e4 MD5 | raw file
1Silver Lining Services 2---------------------- 3 4This document answers some parts of the question: what does Silver 5Lining do, and what does my app do? 6 7The items listed here are things Silver Lining does *for* you, and so 8you shouldn't do them for yourself. 9 10SILVER_VERSION environmental variable 11===================================== 12 13To see if you are running in a Silver Lining production environment, 14check ``os.environ.get('SILVER_VERSION', 15'').startswith('silverlining/')``. In development this variable will 16exist but start with ``'devel/'``. 17 18Secrets 19======= 20 21If you need a "secret" (something random value that is persistent on 22the server), get it like:: 23 24 from silversupport.secret import get_secret 25 secret = get_secret() 26 27This is a stable, ASCII secret. You don't *have* to use this secret 28(you could put a secret in some config file, for instance), this is 29simply offered to you if you want to skip secret generation. It makes 30it easier to put configuration files into version control. This 31secret is *not* put in an environmental variable, because of a 32tendency of environmental variables to leak into error reports and 33other locations. 34 35Temporary files 36=============== 37 38Just kidding; there is no special support for temporary files! This 39is just a reminder to use the `tempfile 40<http://docs.python.org/library/tempfile.html>`_ module like usual; it 41works fine. 42 43Persistence 44=========== 45 46All persistence gets handled in some fashion by Silver Lining. This 47is just so Silver Lining knows about it, and so that your app handles 48what it should. 49 50Files 51~~~~~ 52 53*Persistent* (as opposed to temporary) files need to be handled by 54Silver Lining. In your ``app.ini`` put:: 55 56 service.files = 57 58That line enables the service. Your application then gets the 59environmental variable: 60 61``CONFIG_FILES``: 62 Path to where you can write files. 63 64You only get *one* location for files for your entire app, so it's 65recommended you use additional directories under this location for 66different kinds of files (even if to start you can only think of one 67kind of file). 68 69If you want to use SQLite you could simply require the necessary 70packages (``python-sqlite``) and then use this files service to store 71the database. 72 73Writable Root 74~~~~~~~~~~~~~ 75 76This is another place you can put files, except *these* files will be 77served up publicly. This location is essentially like the ``static/`` 78directory. Files in ``static/`` take precedence, but these files take 79precedence over the dynamic application. To enable use:: 80 81 service.writable_root = 82 83Your application gets the variable:: 84 85``CONFIG_WRITABLE_ROOT``: 86 87 Path where you can write these files. 88 89Note ``index.html`` files will work. 90 91Also you may put files in ``$CONFIG_WRITABLE_ROOT/$HTTP_HOST/...`` for 92per-host files. E.g., you can have an application serve up 93``alice.myblogservice.com`` and ``bob.myblogservice.com``, and put 94their files in ``$CONFIG_WRITABLE_ROOT/alice.myblogservice.com/`` or 95``$CONFIG_WRITABLE_ROOT/bob.myblogservice.com/`` to keep the files 96host-local. 97 98PostGIS 99~~~~~~~ 100 101For PostGIS (PostgreSQL with the PostGIS extensions) do:: 102 103 service.postgis = 104 105Then look for these environmental variables: 106 107``CONFIG_PG_DBNAME``: 108 The database name. 109 110``CONFIG_PG_USER``: 111 The username to connect as. 112 113``CONFIG_PG_PASSWORD``: 114 The password to use (an empty string means no password is required). 115 116``CONFIG_PG_HOST``: 117 The host to connect to; an empty string means localhost. 118 119``CONFIG_PG_PORT``: 120 The port to connect to; an empty string means the default port (5432). 121 122``CONFIG_PG_SQLALCHEMY``: 123 The complete connection string needed for SQLAlchemy. 124 125Right now it's always local, and there won't be any password or host, 126but in the future that might change. And in development you can 127configure it however you want. 128 129MySQL 130~~~~~ 131 132For MySQL do:: 133 134 service.mysql = 135 136Then look for these environmental variables: 137 138``CONFIG_MYSQL_DBNAME``: 139 The database name. 140 141``CONFIG_MYSQL_USERNAME``: 142 The username to connect as. 143 144``CONFIG_MYSQL_PASSWORD``: 145 The password to use (an empty string means no password is required). 146 147``CONFIG_MYSQL_HOST``: 148 The host to connect to; an empty string means localhost. 149 150``CONFIG_MYSQL_PORT``: 151 The port to connect to; an empty string means the default port. 152 153``CONFIG_MYSQL_SQLALCHEMY``: 154 The complete connection string needed for SQLAlchemy. 155 156Right now it's always local, and there won't be any password or host, 157but in the future that might change. And in development you can 158configure it however you want. 159 160CouchDB 161~~~~~~~ 162 163For CouchDB do:: 164 165 service.couchdb = 166 167Then look for: 168 169``CONFIG_COUCHDB_DB``: 170 The name of the database to connect to. 171 172``CONFIG_COUCHDB_HOST``: 173 The host:port to connect to. 174 175MongoDB 176~~~~~~~ 177 178For MongoDB do:: 179 180 service.mongodb = 181 182Then look for: 183 184``CONFIG_MONGODB_DB``: 185 The name of the database to connect to. 186 187``CONFIG_MONGODB_HOST``: 188 The host:port to connect to. 189 190Currently this has several limitations: 191 192It's based on the very alpha ubuntu packages from 10gen 193It works on 9.10 (patching for older versions is simple, choosing is harder) 194It runs the lastest unstable mongodb currently 1.3.x it won't install 1.2.x as no packages are avaliable for it 195 196NFS 197~~~ 198 199To have remote NFS share mounted locally and added to ``/etc/fstab``, do:: 200 201 service.nfs = hostname:/[path] 202 203 204Then look for: 205 206``CONFIG_NFS_DIR``: 207 The local path where remote NFS share is mounted. 208 209Remote NFS share is expected to be available using NFSv4 protocol, on a fixed, 210standard TCP port, number 2049. 211 212This service is not very clever about updating ``/etc/fstab``. If you update 213your application several times with different NFS share locations, you'll end 214up with conflicting entries in ``/etc/fstab``. 215 216 217Installing Packages 218=================== 219 220All your packages should be installed by Silver Lining. You can ask 221for a new (Ubuntu) package to be installed by putting this into your 222``app.ini``:: 223 224 packages = package1 225 package2 226 227This makes Silver Lining run ``apt-get install package1 package2`` 228every time your application is update (conveniently if the packages 229are already installed then ``apt-get`` is fast and does nothing). 230 231Local/Development Configuration 232============================================================ 233 234This all applies to local development (using ``silver serve``), but 235Silver Lining does not actually setup any of this. It's up to you to 236install the necessary servers, create the databases, etc. 237 238You can do this however you want, and effect the configuration using 239``~/.silverlining.conf`` -- each of these services looks for 240configuration overrides here. You should put this configuration in a 241section ``[devel]`` or ``[devel:APP_NAME]`` if you want to override a 242value just for one application (instead of all applications). You 243might do something like:: 244 245 [devel] 246 # Use port 5433, where PG 8.3 is running: 247 postgis.host = localhost:5433 248 249 [devel:someapp] 250 postgis.dbname = foobar 251 252Then all applications will look for the database at 253``localhost:5433``, and the ``someapp`` application will also use the 254database name ``foobar``. If you put the literal string ``APP_NAME`` 255in any configuration value, that will be substituted with the 256application name; you might use it like:: 257 258 [devel] 259 postgis.dbname = test_APP_NAME