src/build/html/_sources/zeo.rst.txt
changeset 0 d153941bb745
equal deleted inserted replaced
-1:000000000000 0:d153941bb745
       
     1 .. _zeo:
       
     2 
       
     3 Creating a ZEO server
       
     4 =====================
       
     5 
       
     6 PyAMS primarily relies on a ZODB database to store it's configuration. Other packages may rely on another
       
     7 database, but *PyAMS_content* package also stores it's contents in a ZODB.
       
     8 
       
     9 As some PyAMS packages start concurrent processes ("synchronization" is done via **ØMQ**), concurrent accesses are
       
    10 required on the ZODB (even when you start your application in "single process" mode) and a ZEO server have to be
       
    11 started.
       
    12 
       
    13 
       
    14 Creating initial buildout
       
    15 -------------------------
       
    16 
       
    17 PyAMS provides a ZEO server scaffold, called *zeo_server*, generated via a *cookiecutter* template.
       
    18 
       
    19 A simple option to create a ZEO server is to create a buildout environment including *ZEO* and *ZODB* packages:
       
    20 
       
    21 .. code-block:: bash
       
    22 
       
    23     # mkdir /var/local/
       
    24     # pip3 install virtualenv
       
    25     # virtualenv --python=python3.5 env
       
    26     # cd env
       
    27     # . bin/activate
       
    28     (env) # pip3.5 install cookiecutter
       
    29     (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server
       
    30 
       
    31 *CookieCutter* will ask you for a small set of input variables that you can change or not:
       
    32 
       
    33 - **pyams_release**: version of PyAMS configuration file to use. "latest" (default value) will point to last release;
       
    34   you can also choose to point to a given release ("0.1.4" for example)
       
    35 
       
    36 - **project_name**: current environment name in "human form"
       
    37 
       
    38 - **project_slug**: "technical" package name, based on project name
       
    39 
       
    40 - **eggs_directory**: relative or absolute path to directory containing downloaded eggs; this directory can be
       
    41   shared with other projects ("eggs" as default)
       
    42 
       
    43 - **run_user**: user name under which ZEO process will run ("zeoadm" as default)
       
    44 
       
    45 - **run_group**: group name under which ZEO process will run ("zeo" as default)
       
    46 
       
    47 - **zeo_server_port**: listening port of ZEO server ("8100" as default)
       
    48 
       
    49 - **zeo_monitor_port**: listening port of ZEO monitor ("8101" as default)
       
    50 
       
    51 - **zeo_storage**: name of first ZEO storage; default value is based on project name
       
    52 
       
    53 - **use_zeo_auth**: specify if ZEO authentication should be used
       
    54 
       
    55 - **zeo_auth_user**: name of ZEO authenticated user (if ZEO authentication is used)
       
    56 
       
    57 - **zeo_auth_password**: password of ZEO authenticated user (if ZEO authentication is used)
       
    58 
       
    59 - **zeo_pack_report**: email address to which pack reports should be sent
       
    60 
       
    61 - **logs_directory**: absolute path to directory containing ZEO's log files.
       
    62 
       
    63 A message is displayed after initialization to finalize environment creation:
       
    64 
       
    65 .. code-block::
       
    66 
       
    67     Your ZEO environment is initialized.
       
    68     To finalize it's creation, just type:
       
    69     - cd zeo_server
       
    70     - python3.5 bootstrap.py
       
    71     - ./bin/buildout
       
    72 
       
    73     To initialize authentication database, please run following command after buildout:
       
    74     ./bin/zeopasswd -f etc/auth.db -p digest -r "ZEO_server" zeouser xxxx
       
    75 
       
    76 
       
    77 ZEO server configuration
       
    78 ------------------------
       
    79 
       
    80 All ZEO configuration files are generated in "etc" subdirectory. These includes:
       
    81 
       
    82 - **etc/zeo_server-zdaemon.conf**: ZDaemon configuration file
       
    83 
       
    84 - **etc/zeo_server-zeo.conf**: ZEO server configuration file
       
    85 
       
    86 - **etc/auth.db**: ZEO authentication file; WARNING: this file is not created automatically, you have to create it
       
    87   after buildout.
       
    88 
       
    89 In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during
       
    90 *CookieCutter* template creation.
       
    91 
       
    92 
       
    93 ZEO server tools
       
    94 ----------------
       
    95 
       
    96 A set of system configuration files are produced to handle your ZEO environment. These includes:
       
    97 
       
    98 - **etc/init.d/zeo-zeo_server**: ZEO server start/stop script in Init-D format. Create a link to this file in
       
    99   */etc/init.d* and update Init.d scripts (*update-rc.d zeo-zeo_server defaults*) to include ZEO in server start/stop
       
   100    process. You can also use this script to start/stop ZEO by hand with *start* and *stop* arguments.
       
   101 
       
   102 - **etc/systemd/zeo-zeo_server.service**: SystemD service configuration file for ZEO server. Create a link to this
       
   103   file in */etc/systemd/system* and reload SystemD daemon (*systemctl daemon-reload*) before activating ZEO service
       
   104   (*systemctl enable zeo-zeo_server.service* and *systemctl start zeo-zeo_server.service*).
       
   105 
       
   106 - **etc/logrotate.d/zeo-zeo_server**: LogRotate configuration file for ZEO log files. Create a link to this file in
       
   107   */etc/logrotate.d* to activate log rotation for ZEO server.
       
   108 
       
   109 - **etc/cron.d/pack-zeo-zeo_server**: Cron configuration file for ZEO database packing. Just create a link to this
       
   110   file in */etc/cron.d* directory to enable ZODB packing on a weekly basis (by default).
       
   111 
       
   112 In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during
       
   113 *CookieCutter* template creation. All directory names are those used on a Debian GNU/Linux distribution and may have
       
   114 to be changed on other distributions.