Installing PyAMS

PyAMS default installation is based on Buildout 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.4; 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 server, to store sessions and cache (can be changed through Beaker configuration)

Optional tools also include:

  • an ElasticSearch server for full text indexing (see PyAMS_content_es package)
  • a WebSockets server using async IO. 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_asyncio scaffold provided by pyams_base package.

You can also choose to use a local ZODB instance, or a ZEO server (which can be local or remote, but is required if you want to use PyAMS in a muti-processes configuration).

Creating initial buildout

PyAMS provides a new Pyramid scaffold, called pyams, provided by the pyams_base package.

A simple option to install PyAMS is to create a buildout environment including Pyramid and PyAMS_base packages:

# mkdir /var/local/env/
# pip3 install virtualenv
# virtualenv --python=python3.4 pyams
# cd pyams
# . bin/activate
(pyams) # pip3.4 install zc.buildout
(pyams) # buildout init

Then update your Buildout configuration file buildout.cfg as follow:

[buildout]
find-links = http://download.ztfy.org/eggs
extends = http://download.ztfy.org/pyams/pyams-0.1.0.cfg
socket-timeout = 3
show-picked-versions = true
newest = false
allow-hosts =
    *.python.org
    *.sourceforge.net
    github.com
    bitbucket.org
versions = versions
eggs-directory = eggs
parts = pyramid

[pyramid]
recipe = zc.recipe.egg
dependent-scripts = true
eggs =
    pyramid
    pyams_base
interpreter = py3.4

Then launch the buildout initialization:

(pyams) # ./bin/buildout
(pyams) # ./bin/pcreate -l
Available scaffolds:
  alchemy:  Pyramid project using SQLAlchemy, SQLite, URL dispatch, and
  pyams:    Pyramid project using all PyAMS packages
  starter:  Pyramid starter project using URL dispatch and Chameleon
  zodb:     Pyramid project using ZODB, traversal, and Chameleon
(pyams) # ./bin/pcreate -t pyams myapp
(pyams) # cd myapp

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:

(pyams) # ../bin/buildout bootstrap
(pyams) # ./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 PyAMS site management)
  • 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 ZODB or a ZEO cache
  • a set of configuration files, in the etc directory; here are standard development.ini and production.ini configuration files, two ZODB configuration files (zodb.conf.fs for a single FileStorage application process, and zodb.conf.zeo for a ZEO client storage; default configuration defined in INI files is based on a single file 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:

(pyams) # ./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:

(pyams) # ./bin/pserve etc/development.ini

In standard debug mode, all registered components are displayed in the console, until the final line (here using ZEO):

2016-12-28 10:58:46,347 INFO  [ZEO.ClientStorage][MainThread] [('localhost', 8100)] ClientStorage (pid=30133) created RW/normal for storage: 'pyams'
2016-12-28 10:58:46,349 DEBUG [ZODB.blob][MainThread] (30133) Blob directory `/var/local/env/pyams/db/blobs` has layout marker set. Selected `bushy` layout.
2016-12-28 10:58:46,349 WARNI [ZODB.blob][MainThread] (30133) Blob dir /var/local/env/pyams/db/blobs/ has insecure mode setting
2016-12-28 10:58:46,349 INFO  [ZEO.cache][MainThread] created temporary cache file 5
2016-12-28 10:58:46,373 BLATH [ZEO.zrpc][MainThread] (30133) CM.connect(): starting ConnectThread
2016-12-28 10:58:46,374 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CT: attempting to connect on 1 sockets
2016-12-28 10:58:46,380 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CW: attempt to connect to ('127.0.0.1', 8100)
2016-12-28 10:58:46,380 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CW: connect_ex(('127.0.0.1', 8100)) returned EINPROGRESS
2016-12-28 10:58:46,381 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CT: select() 0, 1, 0
2016-12-28 10:58:46,381 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CW: connect_ex(('127.0.0.1', 8100)) returned 0
2016-12-28 10:58:46,382 INFO  [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Testing connection <ManagedClientConnection ('127.0.0.1', 8100)>
2016-12-28 10:58:46,383 INFO  [ZEO.zrpc.Connection(b'C')][[('localhost', 8100)] zeo client networking thread] (127.0.0.1:8100) received handshake b'Z3101'
2016-12-28 10:58:46,483 INFO  [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Server authentication protocol None
2016-12-28 10:58:46,484 INFO  [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] Connected to storage: ('localhost', 8100)
2016-12-28 10:58:46,485 INFO  [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] [('localhost', 8100)] No verification necessary -- empty cache
2016-12-28 10:58:46,486 DEBUG [ZEO.ClientStorage][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] pickled inval None b'\x03\xbc>\x1a\x166f"'
2016-12-28 10:58:46,488 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CM.connect_done(preferred=1)
2016-12-28 10:58:46,489 BLATH [ZEO.zrpc][Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])] (30133) CT: exiting thread: Connect([(<AddressFamily.AF_INET: 2>, ('localhost', 8100))])
2016-12-28 10:58:46,676 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyams_template-0.1.0-py3.4.egg/pyams_template/configure.zcml
2016-12-28 10:58:46,677 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyramid_zcml-1.0.0-py3.4.egg/pyramid_zcml/configure.zcml
2016-12-28 10:58:46,678 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyramid_zcml-1.0.0-py3.4.egg/pyramid_zcml/meta.zcml
2016-12-28 10:58:46,684 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyams_template-0.1.0-py3.4.egg/pyams_template/meta.zcml
2016-12-28 10:58:46,710 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyams_viewlet-0.1.0-py3.4.egg/pyams_viewlet/configure.zcml
2016-12-28 10:58:46,711 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyramid_zcml-1.0.0-py3.4.egg/pyramid_zcml/configure.zcml
2016-12-28 10:58:46,711 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyramid_zcml-1.0.0-py3.4.egg/pyramid_zcml/meta.zcml
2016-12-28 10:58:46,746 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/zope.browserpage-4.1.0-py3.4.egg/zope/browserpage/meta.zcml
2016-12-28 10:58:46,825 DEBUG [config][MainThread] include /var/local/env/pyams/eggs/pyams_template-0.1.0-py3.4.egg/pyams_template/meta.zcml
...
2016-12-28 11:02:01,354 DEBUG [PyAMS (utils)][MainThread] Registering adapter <function WfSharedContentIndexInfo at 0x7f506aa9a0d0> for (<InterfaceClass pyams_content.shared.common.interfaces.IWfSharedContent>,) providing <InterfaceClass pyams_content_es.interfaces.IDocumentIndexInfo>
2016-12-28 11:02:01,370 DEBUG [PyAMS (utils)][MainThread] Registering utility <class 'pyams_content_es.site.ContentIndexerGenerationsChecker'> named 'PyAMS content indexer' providing <InterfaceClass pyams_utils.interfaces.site.ISiteGenerations>
2016-12-28 11:02:01,383 DEBUG [PyAMS (pagelet)][MainThread] Registering pagelet view "test-indexer-process.html" for <InterfaceClass pyams_content_es.interfaces.IContentIndexerUtility> (<class 'pyams_content_es.zmi.ContentIndexerProcessTestForm'>)
2016-12-28 11:02:01,387 DEBUG [PyAMS (pagelet)][MainThread] Registering pagelet view "properties.html" for <InterfaceClass pyams_content_es.interfaces.IContentIndexerUtility> (<class 'pyams_content_es.zmi.ContentIndexerUtilityPropertiesEditForm'>)
2016-12-28 11:02:01,400 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_default_theme.configuration.StaticConfiguration'> for (<InterfaceClass pyams_utils.interfaces.site.IStaticConfigurationManager>, <InterfaceClass pyams_default_theme.layer.IPyAMSDefaultLayer>, <InterfaceClass zope.interface.Interface>) providing <InterfaceClass pyams_skin.interfaces.configuration.IStaticConfiguration>
2016-12-28 11:02:01,403 DEBUG [PyAMS (pagelet)][MainThread] Registering pagelet view "" for <InterfaceClass zope.interface.Interface> (<class 'pyams_default_theme.page.BaseIndexPage'>)
2016-12-28 11:02:01,410 DEBUG [PyAMS (utils)][MainThread] Registering utility <class 'pyams_default_theme.skin.PyAMSDefaultSkin'> named 'PyAMS default skin' providing <InterfaceClass pyams_skin.interfaces.ISkin>
2016-12-28 11:02:01,411 DEBUG [PyAMS (utils)][MainThread] Registering adapter <class 'pyams_default_theme.skin.ResourcesAdapter'> for (<InterfaceClass zope.interface.Interface>, <InterfaceClass pyams_default_theme.layer.IPyAMSDefaultLayer>, <InterfaceClass zope.interface.Interface>) providing <InterfaceClass pyams_skin.interfaces.resources.IResources>
Starting server in PID 30235.
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...