/docs/services.txt
Plain Text | 259 lines | 176 code | 83 blank | 0 comment | 0 complexity | 2b04b11b2093d7e158b4515493a773e4 MD5 | raw file
Possible License(s): GPL-2.0
- 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