PageRenderTime 39ms CodeModel.GetById 18ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/services.txt

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