--- a/src/source/zodb.rst Thu Mar 29 13:42:57 2018 +0200
+++ b/src/source/zodb.rst Tue Apr 03 18:17:48 2018 +0200
@@ -1,28 +1,49 @@
.. _zodb:
-Creating ZODB
-=============
+
+ZODB server
+============
+
+
+Installation
+''''''''''''
-PyAMS primarily relies on a ZODB (Zope Objects DataBase) to store it's configuration. Other packages may
-rely on other database(s), but *PyAMS_content* package also stores it's contents in a ZODB.
+PyAMS relies mainly on a ZODB (**\Z**\ope **\O**\bjects **\D**\ata\ **\B**\ase) to store it's configuration and for exemple *PyAMS_content*, but other packages may
+rely on other database(s).
-As some PyAMS packages start several processes ("synchronization" is done via **ØMQ**), concurrent accesses are
-required on the ZODB (even when you start your application in "single process" mode); several ZODB storages
-implementations providing a shared access are available: `ZEO`_, `RelStorage`_ and `Newt.DB`_.
+Concurrent accesses are **required** on the ZODB, to fully enjoy PyAMS.
+Several ZODB storages implementations providing a shared access are available and the installation are describe below:
+
+ * `ZEO Server`_
+ * `RelStorage`_
+ * `Newt.DB`_
-.. _ZEO:
+.. note::
+
+ When you start your application in "*single process*" mode, PyAMS packages start several processes
+ and the "*synchronization*" is done via **ØMQ**.
+
+
-Installing a ZEO server
-+++++++++++++++++++++++
+.. _`ZEO Server`:
-ZEO (Zope Enterprise Objects) is the first available implementation available for concurrent access to a
+1. ZEO server
++++++++++++++
+
+ZEO (**\Z**\ope **\E**\nterprise **\O**\bjects) is the first available implementation available for concurrent access to a
FileStorage, provided through the ZEO package.
-ZEO package documentation and complete configuration settings are available on PyPI.
+.. seealso::
+
+ ZEO package documentation and complete configuration settings are available on PyPI_ (cf: `ZOE 5.2.0`_).
-Creating initial buildout
--------------------------
+.. _PyPI: https://pypi.python.org/pypi/ZEO
+.. _`ZOE 5.2.0`: https://pypi.python.org/pypi/ZEO/5.2.0
+
+
+a) Installation with initial buildout
+-------------------------------------
PyAMS provides a ZEO server scaffold, called *zeo_server*, generated via a *cookiecutter* template.
@@ -30,13 +51,13 @@
.. code-block:: bash
- # mkdir /var/local/
- # pip3 install virtualenv
- # virtualenv --python=python3.5 env
- # cd env
- # . bin/activate
- (env) # pip3.5 install cookiecutter
- (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server
+ $ mkdir /var/local/
+ $ pip3 install virtualenv
+ $ virtualenv --python=python3.5 env
+ $ cd env
+ $ . bin/activate
+ (env) $ pip3.5 install cookiecutter
+ (env) $ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server
*CookieCutter* will ask you for a small set of input variables that you can change or not:
@@ -75,8 +96,8 @@
To initialize authentication database, please run following command after buildout:
./bin/zeopasswd -f etc/auth.db -p digest -r "ZEO_server" zeouser xxxx
-ZEO server configuration
-------------------------
+b) ZEO server configuration
+---------------------------
All ZEO configuration files are generated in "etc" subdirectory. These includes:
@@ -90,8 +111,9 @@
In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during
*CookieCutter* template creation.
-ZEO server tools
-----------------
+
+c) ZEO server tools
+-------------------
A set of system configuration files are produced to handle your ZEO environment. These includes:
@@ -116,8 +138,8 @@
.. _RelStorage:
-Installing a RelStorage server
-++++++++++++++++++++++++++++++
+2. RelStorage server
+++++++++++++++++++++
RelStorage (http://relstorage.readthedocs.io/en/latest) is an alternate ZODB storage implementation, that stores
Python pickles in a relational database; PostgreSQL (>= 9.0), MySQL (>= 5.0.32) and Oracle (> 10g) databases are
@@ -132,8 +154,8 @@
.. _Newt.DB:
-Installing a NewtDB server
-++++++++++++++++++++++++++
+3. NewtDB server
+++++++++++++++++
NewtDB (http://www.newtdb.org/en/latest) is another ZODB storage implementation. It's using RelStorage but is
dedicated to PostgreSQL (>= 9.5).
@@ -150,21 +172,10 @@
if you need to switch from a classic RelStorage database to a Newt database.
-.. _ZODB.init:
-
-Initializing ZODB
-+++++++++++++++++
-
-When your ZODB is created, you have to initialize it!
-
-After installing PyAMS application (see :ref:`appinstall`), a database upgrade script is available which allows you
-to initialize the database. See :ref:`config` and :ref:`scripts` to know more.
-
-
.. _ZODB.migration:
-ZODB migration
-++++++++++++++
+Migration
+'''''''''
After installation, you can switch from a given storage to another one with the help of the *zodbconvert* command
line script provided by RelStorage.
@@ -174,7 +185,8 @@
Here is a sample configuration file to convert a ZODB from a ZEO to RelStorage:
-.. code-block::
+
+.. code-block:: html
%import relstorage
@@ -193,3 +205,5 @@
dsn host='postgresql-server.mydomain' dbname='pyams_rs' user='pyams' password='xxxxxxxx'
</postgresql>
</relstorage>
+
+