/docs/services.txt

  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