[sylvain] r51070 - in silvadoccenter/trunk: . source source/cluster
[email protected] Tue, 3 Sep 2013 18:27:01 +0200 (CEST)
| Newsgroups | gmane.comp.web.zope.silva.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: sylvain
Date: Tue Sep 3 18:27:01 2013
New Revision: 51070
Added:
silvadoccenter/trunk/source/cluster/uploading.rst
silvadoccenter/trunk/source/hosting.rst
silvadoccenter/trunk/source/uwsgi.rst
Modified:
silvadoccenter/trunk/buildout.cfg
silvadoccenter/trunk/source/buildout.rst
silvadoccenter/trunk/source/cluster/index.rst
silvadoccenter/trunk/source/cluster/memcached.rst
silvadoccenter/trunk/source/cluster/relstorage.rst
silvadoccenter/trunk/source/index.rst
silvadoccenter/trunk/source/wsgi.rst
Log:
Various documentation updates (not complete).
Modified: silvadoccenter/trunk/buildout.cfg
==============================================================================
--- silvadoccenter/trunk/buildout.cfg (original)
+++ silvadoccenter/trunk/buildout.cfg Tue Sep 3 18:27:01 2013
@@ -3,7 +3,7 @@
documentation
versions = versions
extends =
- http://svn.infrae.com/buildout/silva/trunk/profiles/silva-development.cfg
+ http://svn.infrae.com/buildout/silva/branch/Silva-3.0/profiles/silva-development.cfg
[versions]
sphinxcontrib.infrae = 1.0
Modified: silvadoccenter/trunk/source/buildout.rst
==============================================================================
--- silvadoccenter/trunk/source/buildout.rst (original)
+++ silvadoccenter/trunk/source/buildout.rst Tue Sep 3 18:27:01 2013
@@ -129,7 +129,11 @@
.. code-block:: sh
- find $buildout/var/uploads -type d -ctime +1 -prune -print0 | xargs -n 1 -0 rm -rf
+ find $buildout/var/uploads -type d -ctime +1 -depth 1 -prune -print0 | xargs -n 1 -0 rm -rf
+
+ The syntax for ``find`` might change depending on your Unix
+ flavor. Please check the proper syntax in your manual before
+ activating this script.
Available configurations
Modified: silvadoccenter/trunk/source/cluster/index.rst
==============================================================================
--- silvadoccenter/trunk/source/cluster/index.rst (original)
+++ silvadoccenter/trunk/source/cluster/index.rst Tue Sep 3 18:27:01 2013
@@ -44,6 +44,24 @@
- An hardware solution (usually expensive).
+In case of large cluster, you can configure an upload server for files:
+
+.. toctree::
+ :maxdepth: 2
+
+ uploading
+
+
+Note about the date and time configuration
+------------------------------------------
+
+If you have multiple physical or virtual servers inside your cluster,
+we recommand you to properly configure each server so their time
+settings is properly synchronized with a common source. You can
+enforce it on Unix by configuring an NTP server with
+``ntpdate``. Failing to do so might creates problems with the default
+authentication method used in Silva.
+
.. _mod_proxy_balancer: http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html
.. _Squid: http://www.squid-cache.org/
.. _Pound: http://www.apsis.ch/pound/
Modified: silvadoccenter/trunk/source/cluster/memcached.rst
==============================================================================
--- silvadoccenter/trunk/source/cluster/memcached.rst (original)
+++ silvadoccenter/trunk/source/cluster/memcached.rst Tue Sep 3 18:27:01 2013
@@ -1,7 +1,7 @@
.. _memcached-setup:
-Configure a cache using memcached
-=================================
+Configuring a cache using memcached
+===================================
Silva can use `memcached`_ as cache backend. It is required to use it
as soon as you have more than one Zope servers hosting the same Silva
@@ -29,6 +29,7 @@
memcache-address = localhost:11211
zope-conf-additional =
<product-config silva.core.cache>
+ memcache ${instance:memcache-address}
default.type ext:memcached
default.lock_dir ${buildout:directory}/var/cache/lock/default
default.url ${instance:memcache-address}
Modified: silvadoccenter/trunk/source/cluster/relstorage.rst
==============================================================================
--- silvadoccenter/trunk/source/cluster/relstorage.rst (original)
+++ silvadoccenter/trunk/source/cluster/relstorage.rst Tue Sep 3 18:27:01 2013
@@ -1,14 +1,15 @@
Store Zope database into a SQL server with RelStorage
=====================================================
-`Relstorage`_ let Zope store its data into a SQL server.
+`Relstorage`_ let Zope stores its data into a SQL server.
Multiple Zope instance can connect simultaneously to the same SQL
-database to use the same data, making possible to distribute the
-requests among those multiple Zope instance. This create an
+database to use the same data, making possible it to distribute the
+requests among those multiple Zope instance. This creates an
installation equivalent to one using ZEO, without ZEO.
-If your SQL server support fail-over, you can have a full fail-over installation.
+If your SQL server support fail-over, you can have a full fail-over
+installation.
Currently, the following SQL servers are supported:
@@ -18,6 +19,9 @@
- Oracle.
+We don't recommand to store the blobs inside the SQL server, but to
+continue to store them on the filesystem, inside a directory that is
+shared among the various servers you have, if you have more than one.
.. warning::
@@ -28,7 +32,8 @@
.. warning::
If you wish to use ZEO *and* RelStorage, the ZEO server should be
- the only client connected the SQL server.
+ the only client connected the SQL server. But ZEO is useless in
+ this case.
Installation with buildout
@@ -53,16 +58,19 @@
cache-local-mb 100
-The line 5 configure the type of SQL database to use. ``postgresql``
-and ``oracle`` are valid options. Line 44 to 47 defines how to connect
-to the MySQL server. Options to connect to PostGreSQl and Oracle are
-different, refer to the documentation of `RelStorage`_ for those.
+- The line 5 configures the type of SQL database to
+ use. ``postgresql`` and ``oracle`` are valid options. Line 44 to 47
+ defines how to connect to the MySQL server. Options to connect to
+ PostGreSQl and Oracle are different, refer to the documentation of
+ `RelStorage`_ for those.
+
+- Line 10 specifies the directory to store Blobs files. *All* Zope
+ servers connected to the SQL database should share the *same* Blobs
+ directory. If they are located on different physical servers, you
+ can share the directory using NFS for instance.
-Line 10 specify the directory to store Blobs files. *All* Zope servers
-connected to the SQL database should share the *same* Blobs directory.
-
-Line 11 define a in memory cache. Don't abuse of this option, install
-`memcached`_ instead.
+- Line 11 define a in memory cache. Don't abuse of this option,
+ install `memcached`_ instead.
Using memcached to improve performances
Added: silvadoccenter/trunk/source/cluster/uploading.rst
==============================================================================
--- (empty file)
+++ silvadoccenter/trunk/source/cluster/uploading.rst Tue Sep 3 18:27:01 2013
@@ -0,0 +1,14 @@
+
+.. _configure-an-upload-server:
+
+Configuring an upload server for files
+======================================
+
+You have the possibility to configure a separate server in order to
+upload files in Silva. This is usefull if you have a large setup
+and/or upload lot of files, since the upload will no longer interfer
+with the performances of the setup (since they can last long, this
+prevent them to block resources).
+
+The upload server is a small WSGI application. Like for Silva, you can
+choose the WSGI server of your choice.
Added: silvadoccenter/trunk/source/hosting.rst
==============================================================================
--- (empty file)
+++ silvadoccenter/trunk/source/hosting.rst Tue Sep 3 18:27:01 2013
@@ -0,0 +1,17 @@
+Presenting your Silva instance to the world
+===========================================
+
+Using ``bin/paster`` is fine for small installation. We recommand to
+configure Apache in front of it in order to have a more user-friendly
+URL in order to access your Silva instance.
+
+For larger installation we recommand to use either uWSGI and NGinx, or
+``mod_wsgi``.
+
+.. toctree::
+ :maxdepth: 2
+
+ apache
+ uwsgi
+ wsgi
+
Modified: silvadoccenter/trunk/source/index.rst
==============================================================================
--- silvadoccenter/trunk/source/index.rst (original)
+++ silvadoccenter/trunk/source/index.rst Tue Sep 3 18:27:01 2013
@@ -23,8 +23,7 @@
buildout
buildout/extending
getting-started-with-silva
- apache
- wsgi
+ hosting
cluster/index
User documentation
Added: silvadoccenter/trunk/source/uwsgi.rst
==============================================================================
--- (empty file)
+++ silvadoccenter/trunk/source/uwsgi.rst Tue Sep 3 18:27:01 2013
@@ -0,0 +1,145 @@
+Configuring uWSGI and Nginx to present your site to the world
+=============================================================
+
+You can install `uWSGI`_ and `Nginx`_ in order to serve your Silva
+site. This is recommanded way for large installations. In this setup
+you will have an `uWSGI`_ instance, that runs, and an `Nginx`_ server
+that connects to it.
+
+.. contents::
+
+Installing uWSGI with buildout
+------------------------------
+
+Because `uWSGI`_ must be compiled with the same Python interpreter
+than the one used to install Silva, and that its configuration
+contains all the paths to the various Python packages used by Silva,
+the best way to install it is to use Buildout. To do so, you need to
+be already familiar with Buildout. If you are not please read
+:ref:`extending-and-customising-your-installation` first.
+
+You can use the recipe `infrae.uwsgi`_ in order to install it:
+
+.. code-block:: buildout
+ :linenos:
+
+ [buildout]
+ parts +=
+ uwsgi
+
+ [uwsgi]
+ recipe = infrae.uwsgi
+ download-url = http://projects.unbit.it/downloads/uwsgi-1.4.9.tar.gz
+ master = True
+ http-socket = 0.0.0.0:8080
+ uwsgi-socket = 127.0.0.1:8081
+ paste = config:${buildout:directory}/deploy.ini
+ paste-logger = True
+ processes = 1
+ threads = 15
+ eggs = ${instance:eggs}
+ single-interpreter = True
+ lazy = True
+ daemonize = ${buildout:directory}/var/log/uwsgi.log
+ pidfile = ${buildout:directory}/var/instance/uwsgi.pid
+
+
+Lines 5 to 19 defines a new part to install ``uwsgi``:
+
+- Line 9 and 10 specify the IP and port number the uWSGI server will
+ bind and listen on. The uWSGI socket defined on line 10 will be used
+ to interact with Nginx. The http socket defined on line 9 is
+ optional, but let you access your uWSGI server with your web
+ browser.
+
+- Line 11 and 12 ask uWSGI to load the Paster configuration generated
+ by buildout, that is used if you start your instance the in a simple
+ fashion (:ref:`starting-creating-silva-site`).
+
+- Lin 13 and 14 defines the number of processus and threads you want
+ to use. If you want to use more than one processus, you need to
+ setup either a RelStorage or a ZEO server (see
+ :ref:`silva-high-availability-installation`). Specify an higher
+ number of threads won't improve at all the performances and might
+ even reduce them.
+
+- Line 17 defines the option ``lazy`` which is critical in order to
+ use the ZODB. **Not specifying this option might result in data
+ lost**.
+
+- Line 18 and 19 tells uWSGI to act as a daemon and go in the
+ background after it started. If you wish to run it as foreground
+ instead you can omit those two directives.
+
+You can specify here in the Buildout configuration any existing `uWSGI
+configuration option`.
+
+
+Managing your uWSGI instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can start your `uWSGI`_ instance like this:
+
+.. code-block:: sh
+
+ $ bin/uwsgi parts/uwsgi/uwsgi.xml
+
+You can stop your `uWSGI`_ instance like this:
+
+.. code-block:: sh
+
+ $ bin/uwsgi --stop var/instance/uwsgi.pid
+
+
+Installing and configuring Nginx
+--------------------------------
+
+Unlike `uWSGI`_, we recommand to install `Nginx`_ using your system
+package manager, and not use Buildout in order to do it.
+
+You can configure `Nginx`_ in order to redirect requests to `uWSGI`_,
+using the default module ngx_http_uwsgi.
+
+.. code-block:: nginx
+ :linenos:
+
+ upstream silva {
+ server 127.0.0.1:8081;
+ }
+
+ server {
+ listen 80;
+ server_name localhost;
+ location / {
+ uwsgi_pass silva;
+ include uwsgi_params;
+ }
+ }
+
+- Line 1 to 3 define an Nginx ``upstream``. You need to specify an IP
+ and port number where a uWSGI server is running: this must be the
+ port number associated with the uWSGI socket, not the http
+ socket. Inside an ``upstream`` section, you have the possiblity to
+ define multiple uWSGI servers, in order to do load-balancing. Other
+ options are available too, like different load-balancing algorithms,
+ backup servers, for more information please refer to the `Nginx
+ documentation`_.
+
+.. note::
+
+ If you have multiple Nginx frontend you will need to
+ :ref:`configure-an-upload-server`.
+
+
+
+Starting and Stopping your site
+-------------------------------
+
+To start you site you need to *start* both uWSGI and Nginx. To stop
+it, well, you can stop uWSGI.
+
+.. _Nginx: http://nginx.org/
+.. _Nginx documentation: http://nginx.org/en/docs/
+.. _uWSGI: http://uwsgi-docs.readthedocs.org/
+.. _uWSGI configuration option: http://uwsgi-docs.readthedocs.org/en/latest/Options.html
+.. _infrae.uwsgi: https://pypi.python.org/pypi/infrae.uwsgi
Modified: silvadoccenter/trunk/source/wsgi.rst
==============================================================================
--- silvadoccenter/trunk/source/wsgi.rst (original)
+++ silvadoccenter/trunk/source/wsgi.rst Tue Sep 3 18:27:01 2013
@@ -3,7 +3,8 @@
Silva now support WSGI. You can use Apache's ``mod_wsgi`` to directly
serve it, without having it running in a different daemon and
-redirecting requests to it. This is the recommend way to use Silva.
+redirecting requests to it. This is the recommend way to use Silva for
+medium-sized installations.
.. contents::
@@ -63,29 +64,29 @@
Explanation
~~~~~~~~~~~
-Line 1 defines a process to run our Silva site with ``mod_wsgi``. The
-options ``user`` and ``group`` defines under which user ``username``
-and group ``username`` the process is going to run. These user
-**must** be the same non-privileged user that you used to install
-Silva. The option ``threads`` defines the number of threads to use in
-each process. **You must not** configure more than 7 threads in any
-case. Finally the option ``maximum-requests`` renew our WSGI process
-every 10000 requests.
-
-Line 7, defines the rewrite rule to trigger Zope VirtualHostMonster,
-so that Zope generates URLs without the identifier ``mysite`` in
-it. The flag ``PT`` tell Apache to transmit the modified URL to the
-next handler, ``mod_wsgi``. For more information about the URL
-rewriting, please reference to :ref:`zope-virtual_host_monster`.
-
-Line 8 specifies the WSGI application to use. This should point to the
-``wsgi`` script creating in your Buildout directory, generated by the
-section ``mod_wsgi_app``.
+- Line 1 defines a process to run our Silva site with
+ ``mod_wsgi``. The options ``user`` and ``group`` defines under which
+ user ``username`` and group ``username`` the process is going to
+ run. These user **must** be the same non-privileged user that you
+ used to install Silva. The option ``threads`` defines the number of
+ threads to use in each process. **You must not** configure more than
+ 7 threads in any case. Finally the option ``maximum-requests`` renew
+ our WSGI process every 10000 requests.
+
+- Line 7, defines the rewrite rule to trigger Zope VirtualHostMonster,
+ so that Zope generates URLs without the identifier ``mysite`` in
+ it. The flag ``PT`` tell Apache to transmit the modified URL to the
+ next handler, ``mod_wsgi``. For more information about the URL
+ rewriting, please reference to :ref:`zope-virtual_host_monster`.
+
+- Line 8 specifies the WSGI application to use. This should point to the
+ ``wsgi`` script creating in your Buildout directory, generated by the
+ section ``mod_wsgi_app``.
-Line 9 tells Apache to the use the process defined on line 1.
+- Line 9 tells Apache to the use the process defined on line 1.
-Line 12 to 15 authorize visitors to access the WSGI application,
-i.e. Silva.
+- Line 12 to 15 authorize visitors to access the WSGI application,
+ i.e. Silva.
Multiple processes
~~~~~~~~~~~~~~~~~~