/docs/services.txt

Silver Lining Services
----------------------

This document answers some parts of the question: what does Silver
Lining do, and what does my app do?

The items listed here are things Silver Lining does *for* you, and so
you shouldn't do them for yourself.

SILVER_VERSION environmental variable
=====================================

To see if you are running in a Silver Lining production environment,
check ``os.environ.get('SILVER_VERSION',
'').startswith('silverlining/')``. In development this variable will
exist but start with ``'devel/'``.

Secrets
=======

If you need a "secret" (something random value that is persistent on
the server), get it like::

    from silversupport.secret import get_secret
    secret = get_secret()

This is a stable, ASCII secret.  You don't *have* to use this secret
(you could put a secret in some config file, for instance), this is
simply offered to you if you want to skip secret generation.  It makes
it easier to put configuration files into version control.  This
secret is *not* put in an environmental variable, because of a
tendency of environmental variables to leak into error reports and
other locations.

Temporary files
===============

Just kidding; there is no special support for temporary files!  This
is just a reminder to use the `tempfile
<http://docs.python.org/library/tempfile.html>`_ module like usual; it
works fine.

Persistence
===========

All persistence gets handled in some fashion by Silver Lining.  This
is just so Silver Lining knows about it, and so that your app handles
what it should.

Files
~~~~~

*Persistent* (as opposed to temporary) files need to be handled by
Silver Lining.  In your ``app.ini`` put::

    service.files =

That line enables the service.  Your application then gets the
environmental variable:

``CONFIG_FILES``:
    Path to where you can write files.

You only get *one* location for files for your entire app, so it's
recommended you use additional directories under this location for
different kinds of files (even if to start you can only think of one
kind of file).

If you want to use SQLite you could simply require the necessary
packages (``python-sqlite``) and then use this files service to store
the database.

Writable Root
~~~~~~~~~~~~~

This is another place you can put files, except *these* files will be
served up publicly.  This location is essentially like the ``static/``
directory.  Files in ``static/`` take precedence, but these files take
precedence over the dynamic application.  To enable use::

    service.writable_root =

Your application gets the variable::

``CONFIG_WRITABLE_ROOT``:

    Path where you can write these files.

Note ``index.html`` files will work.

Also you may put files in ``$CONFIG_WRITABLE_ROOT/$HTTP_HOST/...`` for
per-host files.  E.g., you can have an application serve up
``alice.myblogservice.com`` and ``bob.myblogservice.com``, and put
their files in ``$CONFIG_WRITABLE_ROOT/alice.myblogservice.com/`` or
``$CONFIG_WRITABLE_ROOT/bob.myblogservice.com/`` to keep the files
host-local.

PostGIS
~~~~~~~

For PostGIS (PostgreSQL with the PostGIS extensions) do::

    service.postgis =

Then look for these environmental variables:

``CONFIG_PG_DBNAME``:
    The database name.

``CONFIG_PG_USER``:
    The username to connect as.

``CONFIG_PG_PASSWORD``:
    The password to use (an empty string means no password is required).

``CONFIG_PG_HOST``:
    The host to connect to; an empty string means localhost.

``CONFIG_PG_PORT``:
    The port to connect to; an empty string means the default port (5432).

``CONFIG_PG_SQLALCHEMY``:
    The complete connection string needed for SQLAlchemy.

Right now it's always local, and there won't be any password or host,
but in the future that might change.  And in development you can
configure it however you want.

MySQL
~~~~~

For MySQL do::

    service.mysql =

Then look for these environmental variables:

``CONFIG_MYSQL_DBNAME``:
    The database name.

``CONFIG_MYSQL_USERNAME``:
    The username to connect as.

``CONFIG_MYSQL_PASSWORD``:
    The password to use (an empty string means no password is required).

``CONFIG_MYSQL_HOST``:
    The host to connect to; an empty string means localhost.

``CONFIG_MYSQL_PORT``:
    The port to connect to; an empty string means the default port.

``CONFIG_MYSQL_SQLALCHEMY``:
    The complete connection string needed for SQLAlchemy.

Right now it's always local, and there won't be any password or host,
but in the future that might change.  And in development you can
configure it however you want.

CouchDB
~~~~~~~

For CouchDB do::

    service.couchdb =

Then look for:

``CONFIG_COUCHDB_DB``:
    The name of the database to connect to.

``CONFIG_COUCHDB_HOST``:
    The host:port to connect to.

MongoDB
~~~~~~~

For MongoDB do::

    service.mongodb =

Then look for:

``CONFIG_MONGODB_DB``:
    The name of the database to connect to.

``CONFIG_MONGODB_HOST``:
    The host:port to connect to.

Currently this has several limitations:

It's based on the very alpha ubuntu packages from 10gen
It works on 9.10 (patching for older versions is simple, choosing is harder)
It runs the lastest unstable mongodb currently 1.3.x it won't install 1.2.x as no packages are avaliable for it

NFS
~~~

To have remote NFS share mounted locally and added to ``/etc/fstab``, do::

    service.nfs = hostname:/[path]


Then look for:

``CONFIG_NFS_DIR``:
    The local path where remote NFS share is mounted.

Remote NFS share is expected to be available using NFSv4 protocol, on a fixed, 
standard TCP port, number 2049.

This service is not very clever about updating ``/etc/fstab``. If you update 
your application several times with different NFS share locations, you'll end
up with conflicting entries in ``/etc/fstab``.


Installing Packages
===================

All your packages should be installed by Silver Lining.  You can ask
for a new (Ubuntu) package to be installed by putting this into your
``app.ini``::

    packages = package1
               package2

This makes Silver Lining run ``apt-get install package1 package2``
every time your application is update (conveniently if the packages
are already installed then ``apt-get`` is fast and does nothing).

Local/Development Configuration
============================================================

This all applies to local development (using ``silver serve``), but
Silver Lining does not actually setup any of this.  It's up to you to
install the necessary servers, create the databases, etc.

You can do this however you want, and effect the configuration using
``~/.silverlining.conf`` -- each of these services looks for
configuration overrides here.  You should put this configuration in a
section ``[devel]`` or ``[devel:APP_NAME]`` if you want to override a
value just for one application (instead of all applications).  You
might do something like::

      [devel]
      # Use port 5433, where PG 8.3 is running:
      postgis.host = localhost:5433

      [devel:someapp]
      postgis.dbname = foobar

Then all applications will look for the database at
``localhost:5433``, and the ``someapp`` application will also use the
database name ``foobar``.  If you put the literal string ``APP_NAME``
in any configuration value, that will be substituted with the
application name; you might use it like::

    [devel]
    postgis.dbname = test_APP_NAME