--- a/docs/source/install.rst Thu Jan 11 16:57:23 2018 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,271 +0,0 @@
-.. _install:
-
-Installing PyAMS
-================
-
-PyAMS default installation is based on `Buildout <http://www.buildout.org>`_ utility. It's not mandatory to use a
-virtual environment, but it allows you to have a better control over your Python resources.
-
-Current PyAMS version is based and validated for Python 3.5; your Python environment must also include a C
-compiler as well as development headers for Python, *libjpeg*, *libpng*, *libfreetype*, *libxml2*, *libxslt* and
-eventually *libldap* or *libzmq*.
-
-PyAMS default components configuration also pre-suppose that the following external tools are available:
-
-- a *Memcached* or *Redis* server, to store sessions and cache (can be changed through Beaker configuration)
-
-Optional tools also include:
-
-- an *LDAP* server for authentication
-
-- an *ElasticSearch* server for full text indexing (see *PyAMS_content_es* package)
-
-- a *WebSockets* server using AsyncIO. This is used to manage notifications (see *PyAMS_notify* and *PyAMS_notify_ws*
- packages). An *out of the box* environment can be built using *pyams_notify* scaffold.
-
-
-PyAMS also needs that you use a ZEO server, as several background processes needing a concurrent access to ZODB are
-started by PyAMS main process. See :ref:`zeo` to know how to create a ZEO server with the help of PyAMS tools.
-
-
-Creating initial buildout
--------------------------
-
-PyAMS provides a new Pyramid scaffold, called *pyams*, generated via a *cookiecutter* template.
-
-A simple option to install PyAMS is to create a buildout environment including *Pyramid* and all *PyAMS* 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/pyams
-
-*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
-
-- **virtual_hostname**: Apache virtual-host name
-
-- **webapp_name**: web application package name ("webapp" as default)
-
-- **webapp_port**: TCP/IP port to use when running application outside Apache ("6543" as default)
-
-- **eggs_directory**: relative or absolute path to directory containing downloaded eggs; this directory can be
- shared with other projects ("eggs" as default)
-
-- **logs_directory**: absolute path to directory containing Apache's log files
-
-- **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)
-
-- **beaker_backend**: name of Beaker backend to use to store sessions and cache data ("redis" as default)
-
-- **beaker_server**: IP address and port of Beaker backend server ("127.0.0.1:6379" as default)
-
-- **zeo_server**: IP address and port of ZEO server ("127.0.0.1:8100" as default); WARNING: ZEO server installation
- is not part of application installation; another "zeo_server" cookiecutter receipe is available for that.
-
-- **zeo_storage**: name of ZEO storage to use
-
-- **zeo_username**: ZEO user name
-
-- **zeo_password**: ZEO password
-
-- **zeo_realm**: ZEO authentication realm
-
-- **zeo_blobs_dir**: local directory to use to store cache of ZODB blobs; cache size is limited to 1GB as default
-
-- **use_postgresql**: specify if PostgreSQL access is required; if so, please check that PostgreSQL development files
- are available to compile PsycoPG2 extension
-
-- **use_oracle**: specify if Oracle access is available; if so, please check that Oracle development files are
- available to compile cx_Oracle extension, and that ORACLE_HOME environment variable is correctly defined
-
-- **use_ldap**: specify if LDAP access will be required for authentication
-
-- **use_elasticsearch**: specify if an ElasticSearch server will be used for indexation
-
-- **elasticsearch_server**: URL used to access Elasticsearch server ("http://127.0.0.1:9200" as default); this URL can
- include login and password ("http://login:password@127.0.0.1:9200"), if required...
-
-- **elasticsearch_index**: name of Eslasticsearch index to use ("pyams" as default)
-
-- **create_elasticsearch_index**: specify if Elasticsearch index should be created after installation is complete
-
-- **define_elasticsearch_mappings** : specify if Elasticsearch mappings should be defined after installation is complete
-
-- **smtp_server**: DNS name of SMTP server ("localhost" as default)
-
-- **smtp_server_name**: "human" name given to SMTP server ("pyams" as default)
-
-- **pyams_scheduler**: TCP/IP address and port to use to access PyAMS tasks scheduler process ("127.0.0.1:5555" as
- default)
-
-- **pyams_medias_converter**: TCP/IP address and port to use to access PyAMS medias converter process ("127.0.0.1:5556"
- as default)
-
-- **pyams_es_indexer**: TCP/IP address and port to use to access PyAMS Elasticsearch indexer process ("127.0.0.1:5557"
- as default)
-
-- **use_notifications**: specify if PyAMS notifications services are to be used
-
-- **pyams_ws_notify**: TCP/IP address and port of PyAMS websockets server managing notifications service
- ("127.0.0.1:8081" as default)
-
-- **lexicon_languages**: NLTK lexicon languages to use ("en:english fr:french" as default)
-
-- **extension_package**: name of a PyAMS extension package to include in environment configuration
-
-- **need_pyams_gis**: specify if PyAMS GIS features are to be used by given extension package; if so, please check
- that *libgdal* development files are available and on Debian, you have to specify environment variables for
- C_INCLUDE_PATH and CPLUS_INCLUDE_PATH pointing to */usr/include/gdal* directory. WARNING: you have to check also
- that your *libgdal* release is matching "GDAL" release given in PyAMS configuration file (actually 2.1.0).
-
-
-You can then check, and eventually update, the proposed Buildout configuration file *buildout.cfg*, to add or remove
-packages or update settings to your needs. Then finalize Bootstrap initialization:
-
-.. code-block:: bash
-
- (env) # python3.5 bootstrap.py
- (env) # ./bin/buildout
-
-This last operation can be quite long, as many packages have to downloaded, compiled and installed in the virtual
-environment. If you encounter any compile error, just install the required dependencies and restart the buildout.
-
-
-Environment settings
---------------------
-
-The project generated from *pyams* scaffold is based on default Pyramid's *zodb* scaffold, but it adds:
-
-- a custom application factory, in the *webapp* directory (see :ref:`site`)
-
-- a set of directories to store runtime data, in the *var* directory; each directory contains a *README.txt* file
- which should be self-explanatory to indicate what this directory should contain, including a ZEO cache
-
-- a set of configuration files, in the *etc* directory; here are standard *development.ini* and *production.ini*
- configuration files, a ZODB configuration files (*zodb-zeo.conf*) for a ZEO client storage and two Apache
- configurations (for Apache 2.2 and 2.4) using *mod_wsgi*.
-
-Once the project have been created from the scaffold, you are free to update all the configuration files.
-
-If you need to add packages to the environment, you have to add them to the *buildout.cfg* file **AND** to the INI
-file (in the *pyramid.includes* section) before running the *buildout* another time; don't forget to add the
-requested version at the end of *buildout.cfg* file, as Buildout is not configured by default to automatically
-download the last release of a given unknown package.
-
-*development.ini* and *production.ini* files contain many commented directives related to PyAMS components. Read and
-update them carefully before initializing your application database!
-
-
-Initializing the database
--------------------------
-
-When you have downloaded and installed all required packages, you have to initialize the database so that all
-required components are available.
-
-From a shell, just type:
-
-.. code-block:: bash
-
- (env) # ./bin/pyams_upgrade etc/development.ini
-
-This process requires that every package is correctly included into *pyramid.includes* directive from selected
-configuration file.
-
-
-Starting the application
-------------------------
-
-When database upgrade process has ended, you can start the web application process with the standard Pyramid's
-*pserve* command line tool:
-
-.. code-block:: bash
-
- (env) # ./bin/pserve etc/development.ini
-
-In standard debug mode, all registered components are displayed in the console, until the final line (here using ZEO):
-
-.. code-block:: bash
-
- 2017-06-19 17:21:40,495 INFO [ZEO.ClientStorage][MainThread] [('localhost', 8100)] ClientStorage (pid=23253) created RW/normal for storage: 'pyams'
- 2017-06-19 17:21:40,497 DEBUG [ZODB.blob][MainThread] (23253) Blob directory `var/db/blobs` has layout marker set. Selected `bushy` layout.
- 2017-06-19 17:21:40,497 WARNI [ZODB.blob][MainThread] (23253) Blob dir var/db/blobs/ has insecure mode setting
- 2017-06-19 17:21:40,498 INFO [ZEO.cache][MainThread] created temporary cache file 4
- 2017-06-19 17:21:40,517 BLATH [ZEO.zrpc][MainThread] (23253) CM.connect(): starting ConnectThread
- 2017-06-19 17:21:40,518 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CT: attempting to connect on 1 sockets
- 2017-06-19 17:21:40,524 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CW: attempt to connect to ('127.0.0.1', 8100)
- 2017-06-19 17:21:40,525 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned EINPROGRESS
- 2017-06-19 17:21:40,525 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CT: select() 0, 1, 0
- 2017-06-19 17:21:40,526 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned 0
- 2017-06-19 17:21:40,526 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Testing connection <ManagedClientConnection ('127.0.0.1', 8100)>
- 2017-06-19 17:21:40,527 INFO [ZEO.zrpc.Connection(b'C')][[('localhost', 8100)] zeo client networking thread] (127.0.0.1:8100) received handshake b'Z4'
- 2017-06-19 17:21:40,628 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Server authentication protocol None
- 2017-06-19 17:21:40,629 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Connected to storage: ('localhost', 8100)
- 2017-06-19 17:21:40,630 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] No verification necessary -- empty cache
- 2017-06-19 17:21:40,631 DEBUG [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] pickled inval None b'\x03\xc0\n*g\xcf\xcd\xbb'
- 2017-06-19 17:21:40,633 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CM.connect_done(preferred=1)
- ...
- 2017-06-19 17:22:39,342 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardModifiedColumn'> for (<InterfaceClass zope.interface.Interface>, <InterfaceClass pyams_skin.layer.IPyAMSLayer>, <InterfaceClass pyams_content.shared.common.interfaces.zmi.ISharedToolDashboardTable>) providing <InterfaceClass z3c.table.interfaces.IColumn>
- 2017-06-19 17:22:39,342 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardNameAdapter'> for (<InterfaceClass pyams_content.shared.common.interfaces.ISharedTool>, <InterfaceClass pyams_skin.layer.IPyAMSLayer>, <InterfaceClass pyams_content.shared.common.interfaces.zmi.IDashboardTable>) providing <InterfaceClass pyams_skin.interfaces.container.ITableElementName>
- 2017-06-19 17:22:39,343 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardNameColumn'> for (<InterfaceClass zope.interface.Interface>, <InterfaceClass pyams_skin.layer.IPyAMSLayer>, <InterfaceClass pyams_content.shared.common.interfaces.zmi.ISharedToolDashboardTable>) providing <InterfaceClass z3c.table.interfaces.IColumn>
- 2017-06-19 17:22:39,344 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardOwnerColumn'> for (<InterfaceClass zope.interface.Interface>, <InterfaceClass pyams_skin.layer.IPyAMSLayer>, <InterfaceClass pyams_content.shared.common.interfaces.zmi.ISharedToolDashboardTable>) providing <InterfaceClass z3c.table.interfaces.IColumn>
- 2017-06-19 17:22:39,344 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardOwnerModifiedValues'> for (<InterfaceClass pyams_content.shared.common.interfaces.ISharedTool>, <InterfaceClass pyams_skin.layer.IPyAMSLayer>, <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardOwnerModifiedTable'>) providing <InterfaceClass z3c.table.interfaces.IValues>
- 2017-06-19 17:22:39,345 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardOwnerWaitingValues'> for (<InterfaceClass pyams_content.shared.common.interfaces.ISharedTool>, <InterfaceClass pyams_skin.layer.IPyAMSLayer>, <class 'pyams_content.shared.common.zmi.dashboard.SharedToolDashboardOwnerWaitingTable'>) providing <InterfaceClass z3c.table.interfaces.IValues>
- ...
- 2017-06-19 17:22:40,221 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'onf_website.root.SiteRootStaticConfiguration'> for (<InterfaceClass onf_website.root.interfaces.ISiteRoot>, <InterfaceClass zope.interface.Interface>, <InterfaceClass zope.interface.Interface>) providing <InterfaceClass pyams_skin.interfaces.configuration.IStaticConfiguration>
- 2017-06-19 17:22:40,222 DEBUG [PyAMS (utils)][MainThread] Registering adapter <function site_root_tools_configuration_factory at 0x7fbc923bb158> for (<InterfaceClass onf_website.root.interfaces.ISiteRoot>,) providing <InterfaceClass onf_website.root.interfaces.ISiteRootToolsConfiguration>
- 2017-06-19 17:22:40,233 DEBUG [PyAMS (utils)][MainThread] Registering adapter <function NewsManagerRestrictionsFactory at 0x7fbc92266ae8> for (<InterfaceClass onf_website.shared.news.interfaces.INewsManager>,) providing <InterfaceClass pyams_content.shared.common.interfaces.IManagerRestrictionsFactory>
- 2017-06-19 17:22:40,244 DEBUG [config][MainThread] include onf_website/configure.zcml
- 2017-06-19 17:22:40,245 DEBUG [config][MainThread] include eggs/pyramid_zcml-1.1.0-py3.5.egg/pyramid_zcml/configure.zcml
- 2017-06-19 17:22:40,246 DEBUG [config][MainThread] include eggs/pyramid_zcml-1.1.0-py3.5.egg/pyramid_zcml/meta.zcml
- 2017-06-19 17:22:40,252 DEBUG [config][MainThread] include eggs/zope.i18n-4.1.0-py3.5.egg/zope/i18n/meta.zcml
- 2017-06-19 17:22:40,253 DEBUG [zope.i18n][MainThread] register directory onf_website/src/onf_website/locales
- 2017-06-19 17:22:40,258 DEBUG [config][MainThread] include webapp/webapp/configure.zcml
- ...
- 2017-06-19 17:22:41,288 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CM.connect_done(preferred=1)
- 2017-06-19 17:22:41,288 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CT: exiting thread: Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])
- 2017-06-19 17:22:41,303 DEBUG [PyAMS (scheduler][MainThread] Adding scheduler job for task 'Compactage ZEO'
- 2017-06-19 17:22:41,304 INFO [apscheduler.scheduler][MainThread] Adding job tentatively -- it will be properly scheduled when the scheduler starts
- 2017-06-19 17:22:41,305 DEBUG [PyAMS (scheduler][MainThread] Starting tasks scheduler <SchedulerProcess(SchedulerProcess-1, initial)>...
- 2017-06-19 17:22:41,313 INFO [apscheduler.scheduler][MainThread] Added job "Compactage ZEO" to job store "default"
- 2017-06-19 17:22:41,314 INFO [apscheduler.scheduler][MainThread] Scheduler started
- 2017-06-19 17:22:41,314 DEBUG [apscheduler.scheduler][APScheduler] Looking for jobs to run
- 2017-06-19 17:22:41,315 DEBUG [apscheduler.scheduler][APScheduler] Next wakeup is due at 2017-06-20 03:00:00+02:00 (in 34638.684629 seconds)
- 2017-06-19 17:22:41,326 INFO [ZEO.ClientStorage][MainThread] [('localhost', 8100)] ClientStorage (pid=23253) created RW/normal for storage: 'pyams'
- 2017-06-19 17:22:41,327 DEBUG [ZODB.blob][MainThread] (23253) Blob directory `var/db/blobs` has layout marker set. Selected `bushy` layout.
- 2017-06-19 17:22:41,328 WARNI [ZODB.blob][MainThread] (23253) Blob dir var/db/blobs/ has insecure mode setting
- 2017-06-19 17:22:41,329 INFO [ZEO.cache][MainThread] created temporary cache file 15
- 2017-06-19 17:22:41,382 BLATH [ZEO.zrpc][MainThread] (23253) CM.connect(): starting ConnectThread
- 2017-06-19 17:22:41,383 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CT: attempting to connect on 1 sockets
- 2017-06-19 17:22:41,383 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CW: attempt to connect to ('127.0.0.1', 8100)
- 2017-06-19 17:22:41,384 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned EINPROGRESS
- 2017-06-19 17:22:41,385 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CT: select() 0, 1, 0
- 2017-06-19 17:22:41,385 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned 0
- 2017-06-19 17:22:41,386 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Testing connection <ManagedClientConnection ('127.0.0.1', 8100)>
- 2017-06-19 17:22:41,386 INFO [ZEO.zrpc.Connection(b'C')][[('localhost', 8100)] zeo client networking thread] (127.0.0.1:8100) received handshake b'Z4'
- 2017-06-19 17:22:41,487 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Server authentication protocol None
- 2017-06-19 17:22:41,488 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Connected to storage: ('localhost', 8100)
- 2017-06-19 17:22:41,489 INFO [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] No verification necessary -- empty cache
- 2017-06-19 17:22:41,490 DEBUG [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] pickled inval None b'\x03\xc0\n*g\xcf\xcd\xbb'
- 2017-06-19 17:22:41,492 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CM.connect_done(preferred=1)
- 2017-06-19 17:22:41,493 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (23253) CT: exiting thread: Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])
- 2017-06-19 17:22:41,498 DEBUG [PyAMS (media)][MainThread] Starting medias conversion process <MediaConversionProcess(MediaConversionProcess-2, initial)>...
- 2017-06-19 17:22:41,503 DEBUG [PyAMS (content.es)][MainThread] Starting content indexer process <ContentIndexerProcess(ContentIndexerProcess-3, initial)>...
- Starting server in PID 23253.
- Serving on http://0.0.0.0:6543
-
-From this point, you can launch a browser and open URL *http://127.0.0.1:6543/admin* to get access to PyAMS
-management interface; default login is "admin/admin", that you may change as soon as possible...