--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/build/html/install.html Tue Nov 22 21:35:46 2016 +0100
@@ -0,0 +1,235 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Installing PyAMS — PyAMS_utils 0.1.4 documentation</title>
+
+ <link rel="stylesheet" href="_static/pyramid.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '0.1.4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="top" title="PyAMS_utils 0.1.4 documentation" href="index.html" />
+ <link rel="next" title="Managing ZCA with PyAMS" href="zca.html" />
+ <link rel="prev" title="Welcome to PyAMS_utils’s documentation!" href="index.html" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Neuton&subset=latin" type="text/css" media="screen" charset="utf-8" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&subset=latin" type="text/css" media="screen" charset="utf-8" />
+<!--[if lte IE 6]>
+<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
+<![endif]-->
+
+ </head>
+ <body role="document">
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="py-modindex.html" title="Python Module Index"
+ >modules</a> |</li>
+ <li class="right" >
+ <a href="zca.html" title="Managing ZCA with PyAMS"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="Welcome to PyAMS_utils’s documentation!"
+ accesskey="P">previous</a> |</li>
+ <li class="nav-item nav-item-0"><a href="index.html">PyAMS_utils 0.1.4 documentation</a> »</li>
+ </ul>
+ </div>
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="installing-pyams">
+<span id="install"></span><h1>Installing PyAMS<a class="headerlink" href="#installing-pyams" title="Permalink to this headline">¶</a></h1>
+<p>PyAMS default installation is based on <a class="reference external" href="http://www.buildout.org">Buildout</a> utility. It’s not mandatory to use a
+virtual environment, but it allows you to have a better control over your Python resources.</p>
+<p>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, <em>libjpeg</em>, <em>libpng</em>, <em>libfreetype</em>, <em>libxml2</em>, <em>libxslt</em> and
+eventually <em>libldap</em> or <em>libzmq</em>.</p>
+<p>PyAMS default components configuration also pre-suppose that the following external tools are available:</p>
+<ul class="simple">
+<li>a <em>memcached</em> server, to store sessions and cache (can be changed through Beaker configuration)</li>
+</ul>
+<p>Optional tools also include:</p>
+<ul class="simple">
+<li>an <em>ElasticSearch</em> server for full text indexing (see <em>PyAMS_content_es</em> package)</li>
+<li>a <em>WebSockets</em> server using async IO. This is used to manage notifications (see <em>PyAMS_notify</em> and <em>PyAMS_notify_ws</em>
+packages). An <em>out of the box</em> environment can be built using <em>pyams_asyncio</em> scaffold provided by <em>pyams_base</em>
+package.</li>
+</ul>
+<p>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).</p>
+<div class="section" id="creating-initial-buildout">
+<h2>Creating initial buildout<a class="headerlink" href="#creating-initial-buildout" title="Permalink to this headline">¶</a></h2>
+<p>PyAMS provides a new Pyramid scaffold, called <em>pyams</em>, provided by the <em>pyams_base</em> package.</p>
+<p>A simple option to install PyAMS is to create a buildout environment including <em>Pyramid</em> and <em>PyAMS_base</em> packages:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># mkdir /var/local/env/</span>
+<span class="c"># pip3 install virtualenv</span>
+<span class="c"># virtualenv --python=python3.4 pyams</span>
+<span class="c"># cd pyams</span>
+<span class="c"># . bin/activate</span>
+<span class="o">(</span>pyams<span class="o">)</span> <span class="c"># pip3.4 install zc.buildout</span>
+<span class="o">(</span>pyams<span class="o">)</span> <span class="c"># buildout init</span>
+</pre></div>
+</div>
+<p>Then update your Buildout configuration file <em>buildout.cfg</em> as follow:</p>
+<div class="highlight-ini"><div class="highlight"><pre><span class="k">[buildout]</span>
+<span class="na">find-links</span> <span class="o">=</span> <span class="s">http://download.ztfy.org/eggs</span>
+<span class="na">extends</span> <span class="o">=</span> <span class="s">http://download.ztfy.org/pyams/pyams-0.1.0.cfg</span>
+<span class="na">socket-timeout</span> <span class="o">=</span> <span class="s">3</span>
+<span class="na">show-picked-versions</span> <span class="o">=</span> <span class="s">true</span>
+<span class="na">newest</span> <span class="o">=</span> <span class="s">false</span>
+<span class="na">allow-hosts</span> <span class="o">=</span><span class="s"></span>
+<span class="s"> *.python.org</span>
+<span class="s"> *.sourceforge.net</span>
+<span class="s"> github.com</span>
+<span class="s"> bitbucket.org</span>
+<span class="na">versions</span> <span class="o">=</span> <span class="s">versions</span>
+<span class="na">eggs-directory</span> <span class="o">=</span> <span class="s">eggs</span>
+<span class="na">parts</span> <span class="o">=</span> <span class="s">pyramid</span>
+
+<span class="k">[pyramid]</span>
+<span class="na">recipe</span> <span class="o">=</span> <span class="s">zc.recipe.egg</span>
+<span class="na">dependent-scripts</span> <span class="o">=</span> <span class="s">true</span>
+<span class="na">eggs</span> <span class="o">=</span><span class="s"></span>
+<span class="s"> pyramid</span>
+<span class="s"> pyams_base</span>
+<span class="na">interpreter</span> <span class="o">=</span> <span class="s">py3.4</span>
+</pre></div>
+</div>
+<p>Then launch the buildout initialization:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="o">(</span>pyams<span class="o">)</span> <span class="c"># ./bin/buildout</span>
+<span class="o">(</span>pyams<span class="o">)</span> <span class="c"># ./bin/pcreate -l</span>
+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
+<span class="o">(</span>pyams<span class="o">)</span> <span class="c"># ./bin/pcreate -t pyams myapp</span>
+<span class="o">(</span>pyams<span class="o">)</span> <span class="c"># cd myapp</span>
+</pre></div>
+</div>
+<p>You can then check, and eventually update, the proposed Buildout configuration file <em>buildout.cfg</em>, to add or remove
+packages or update settings to your needs. Then finalize Bootstrap initialization:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="o">(</span>pyams<span class="o">)</span> <span class="c"># ../bin/buildout bootstrap</span>
+<span class="o">(</span>pyams<span class="o">)</span> <span class="c"># ./bin/buildout</span>
+</pre></div>
+</div>
+<p>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.</p>
+</div>
+<div class="section" id="environment-settings">
+<h2>Environment settings<a class="headerlink" href="#environment-settings" title="Permalink to this headline">¶</a></h2>
+<p>The project generated from <em>pyams</em> scaffold is based on default Pyramid’s <em>zodb</em> scaffold, but it adds:</p>
+<ul class="simple">
+<li>a custom application factory, in the <em>webapp</em> directory (see <a class="reference internal" href="site.html#site"><span class="std std-ref">PyAMS site management</span></a>)</li>
+<li>a set of directories to store runtime data, in the <em>var</em> directory; each directory contains a <em>README.txt</em> file
+which should be self-explanatory to indicate what this directory should contain, including a ZODB or a ZEO cache</li>
+<li>a set of configuration files, in the <em>etc</em> directory; here are standard <em>development.ini</em> and <em>production.ini</em>
+configuration files, two ZODB configuration files (<em>zodb.conf.fs</em> for a single FileStorage application process, and
+<em>zodb.conf.zeo</em> 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 <em>mod_wsgi</em>.</li>
+</ul>
+<p>Once the project have been created from the scaffold, you are free to update all the configuration files.</p>
+<p>If you need to add packages to the environment, you have to add them to the <em>buildout.cfg</em> file <strong>AND</strong> to the INI
+file (in the <em>pyramid.includes</em> section) before running the <em>buildout</em> another time; don’t forget to add the
+requested version at the end of <em>buildout.cfg</em> file, as Buildout is not configured by default to automatically
+download the last release of a given unknown package.</p>
+<p><em>development.ini</em> and <em>production.ini</em> files contain many commented directives related to PyAMS components. Read and
+update them carefully before initializing your application database!</p>
+</div>
+<div class="section" id="initializing-the-database">
+<h2>Initializing the database<a class="headerlink" href="#initializing-the-database" title="Permalink to this headline">¶</a></h2>
+<p>When you have downloaded and installed all required packages, you have to initialize the database so that all
+required components are available.</p>
+<p>From a shell, just type:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="o">(</span>pyams<span class="o">)</span> <span class="c"># ./bin/pyams_upgrade etc/development.ini</span>
+</pre></div>
+</div>
+<p>This process requires that every package is correctly included into <em>pyramid.includes</em> directive from selected
+configuration file.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Installing PyAMS</a><ul>
+<li><a class="reference internal" href="#creating-initial-buildout">Creating initial buildout</a></li>
+<li><a class="reference internal" href="#environment-settings">Environment settings</a></li>
+<li><a class="reference internal" href="#initializing-the-database">Initializing the database</a></li>
+</ul>
+</li>
+</ul>
+
+ <h4>Previous topic</h4>
+ <p class="topless"><a href="index.html"
+ title="previous chapter">Welcome to PyAMS_utils’s documentation!</a></p>
+ <h4>Next topic</h4>
+ <p class="topless"><a href="zca.html"
+ title="next chapter">Managing ZCA with PyAMS</a></p>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="py-modindex.html" title="Python Module Index"
+ >modules</a> |</li>
+ <li class="right" >
+ <a href="zca.html" title="Managing ZCA with PyAMS"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="Welcome to PyAMS_utils’s documentation!"
+ >previous</a> |</li>
+ <li class="nav-item nav-item-0"><a href="index.html">PyAMS_utils 0.1.4 documentation</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2016, Thierry Florac <tflorac@ulthar.net>.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.8.
+ </div>
+ </body>
+</html>
\ No newline at end of file