--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/source/zeo.rst	Wed Jul 12 13:57:06 2017 +0200
@@ -0,0 +1,114 @@
+.. _zeo:
+
+Creating a ZEO server
+=====================
+
+PyAMS primarilly relies on a ZODB database to it's store itt's configuration. Other packages may rely on another
+database, but *PyAMS_content* package also stores it's contents in a ZODB.
+
+As some PyAMS packages start concurrent processes ("synchronization" is done via **ØMQ**), concurrent accesses are
+required on the ZODB (event when you start your application in "single process" mode) and a ZEO server have to be
+started.
+
+
+Creating initial buildout
+-------------------------
+
+PyAMS provides a ZEO server scaffold, called *zeo_server*, generated via a *cookiecutter* template.
+
+A simple option to create a ZEO server is to create a buildout environment including *ZEO* and *ZODB* packages:
+
+.. 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
+
+*CookieCutter* will ask you for a small set of input variables that you can change or not:
+
+- **pyams_release**: version of PyAMS configuration file to use. "latest" (default value) will point to last release;
+  you can also choose to point to a given release ("0.1.4" for example)
+
+- **project_name**: current environment name in "human form"
+
+- **project_slug**: "technical" package name, based on project name
+
+- **eggs_directory**: relative or absolute path to directory containing downloaded eggs; this directory can be
+  shared with other projects ("eggs" as default)
+
+- **run_user**: user name under which Apache process will run ("www-data" as default)
+
+- **run_group**: group name under which Apache process will run ("www-data" as default)
+
+- **zeo_server_port**: listening port of ZEO server ("8100" as default)
+
+- **zeo_monitor_port**: listening port of ZEO monitor ("8101" as default)
+
+- **zeo_storage**: name of first ZEO storage; default value is based on project name
+
+- **use_zeo_auth**: specify if ZEO authentication should be used
+
+- **zeo_auth_user**: name of ZEO authenticated user (if ZEO authentication is used)
+
+- **zeo_auth_password**: password of ZEO authenticated user (if ZEO authentication is used)
+
+- **zeo_pack_report**: email address to which pack reports should be sent
+
+- **logs_directory**: absolute path to directory containing ZEO's log files.
+
+A message is displayed after initialization to finalize environment creation:
+
+.. code-block::
+
+    Your ZEO environment is initialized.
+    To finalize it's creation, just type:
+    - cd zeo_server
+    - python3.5 bootstrap.py
+    - ./bin/buildout
+
+    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
+------------------------
+
+All ZEO configuration files are generated in "etc" subdirectory. These includes:
+
+- **etc/zeo_server-zdaemon.conf**: ZDaemon configuration file
+
+- **etc/zeo_server-zeo.conf**: ZEO server configuration file
+
+- **etc/auth.db**: ZEO authentication file; WARNING: this file is not created automatically, you have to create it
+  after buildout.
+
+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
+----------------
+
+A set of system configuration files are produced to handle your ZEO environment. These includes:
+
+- **etc/init.d/zeo-zeo_server**: ZEO server start/stop script in Init-D format. Create a link to this file in
+  */etc/init.d* and update Init.d scripts (*update-rc.d zeo-zeo_server defaults*) to include ZEO in server start/stop
+   process. You can also use this script to start/stop ZEO by hand with *start* and *stop* arguments.
+
+- **etc/systemd/zeo-zeo_server.service**: SystemD service configuration file for ZEO server. Create a link to this
+  file in */etc/systemd/system* and reload SystemD daemon (*systemctl daemon-reload*) before activating ZEO service
+  (*systemctl enable zeo-zeo_server.service* and *systemctl start zeo-zeo_server.service*).
+
+- **etc/logrotate.d/zeo-zeo_server**: LogRotate configuration file for ZEO log files. Create a link to this file in
+  */etc/logrotate.d* to activate log rotation for ZEO server.
+
+- **etc/cron.d/pack-zeo-zeo_server**: Cron configuration file for ZEO database packing. Just create a link to this
+  file in */etc/cron.d* directory to enable ZODB packing on a weekly basis (by default).
+
+In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during
+*CookieCutter* template creation. All directory names are those used on a Debian GNU/Linux distribution and may have
+to be changed on other distributions.