diff -r 4cddbff4269f -r 78f842f992a0 src/source/quickstart.rst --- a/src/source/quickstart.rst Fri Mar 23 11:50:01 2018 +0100 +++ b/src/source/quickstart.rst Mon Mar 26 11:12:28 2018 +0200 @@ -13,25 +13,20 @@ 0. Before starting ++++++++++++++++++ - -**a. Package required** +Required packages +----------------- - -PyAMS relies on Python packages for which you must have system packages available in your environment. - +PyAMS relies on system and Python packages which you must have been previously installed in your environment. .. note:: - - C/C++ compiler like **GCC** - - **Python 3.5*** with development headers or **Cython3** for better optimization of several packages - - Cache server, like **Redis** or **Memcached**. + - a C/C++ compiler like **GCC** + - **Python 3.5*** with development headers; **Cython3** for better optimization of several packages + - a cache server, like **Redis** or **Memcached**. + - Several libraries with their development headers: *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt* + (and *libpq* if you want to use PostgreSQL, *libldap* if you want to use LDAP authentication...). - - Several libraries with their development headers: - - => *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt* (and *libpq* if you want to use PostgreSQL) - - -*PyAMS may be compatible with other versions but has only been completely tested with this version until now +* PyAMS may be compatible with other versions but has only been completely tested with this version until now. On a Debian GNU/Linux: @@ -43,8 +38,8 @@ $ apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev -**b. Initialize virtual environment** - +Initialize virtual environment +------------------------------ We are creating a virtual environment in */var/local/env* @@ -55,24 +50,23 @@ $ virtualenv --python=python3.5 env $ source env/bin/activate -To use PyAMS templates *cookiecutter* is required +To use PyAMS templates, the *cookiecutter* tool is required: .. code-block:: bash (env)$ pip3.5 install cookiecutter - 1. Create ZODB ++++++++++++++ -We are creating a local ZODB using ZEO server using cookiecutter template +We are creating a local ZODB using a "ZEO server" cookiecutter template. -.. tip:: To know more about ZODB storage you can see :ref:`zodb`. +.. tip:: To know more about ZODB storages you can see :ref:`zodb`. .. note:: - In this example, ZEO server instance will run as UNIX user and group. For a production + In this example, ZEO server instance will run as current UNIX user and group. For a production environment, it's better to use dedicated service user and group. Run cookiecutter: @@ -89,13 +83,13 @@ pyams_release [latest]: project_name [ZEO_server]: ZEO_pyams project_slug [zeo_pyams]: - eggs_directory [eggs]: /var/local/eggs #Python eggs will be stored into */var/local/eggs* directory. - run_user [zeo]: mylogin - run_group [zeo]: mygroup + eggs_directory [eggs]: /var/local/eggs # Python eggs will be stored into */var/local/eggs* directory. + run_user [zeo]: mylogin # current user ID + run_group [zeo]: mygroup # current user group zeo_server_port [8100]: zeo_storage [pyams]: zeo_pack_report [root@localhost]: email@my-domain.com - logs_directory [/var/log/zeo/zeo_pyams]: #Absolute path is mandatory + logs_directory [/var/log/zeo/zeo_pyams]: # An absolute path is mandatory!!! Your ZEO environment is initialized. To finalize it\'s creation, just type: @@ -104,7 +98,7 @@ - ./bin/buildout -In *zeo_pyams* folder, execute *bootstrap.py*... +In *zeo_pyams* folder, execute *bootstrap.py*: .. code-block:: bash @@ -117,7 +111,7 @@ Generated script '/var/local/env/zeo_pyams/bin/buildout'. -...and then run *buildout* +And then run final *buildout*: .. code-block:: bash @@ -145,27 +139,23 @@ daemon process started, pid=26230 - - 2. Create application instance -+++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++ Application instance will be created in */var/local/env/pyams* via another coockiecutter template: -.. tip:: - .. code-block:: bash (env)$ cd /var/local/env (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams -Configuration +.. tip:: Configuration -.. tip:: - - 1. The variable *$((INSTALL))* is the path path to current folder - 2. You will be invited setup supplementary services like **elastics search** but you must to install them on your own. + 1. The variable **$((INSTALL))** is the path to current folder; it will be replaced automatically by cookiecutter + after application creation + 2. You will be invited to setup additional services like **Elasticsearch** but you must install them on + your own. .. code-block:: bash @@ -177,9 +167,9 @@ webapp_name [webapp]: webapp_port [6543]: eggs_directory [eggs]: - logs_directory [ $((INSTALL))/var/log]: - run_user [www-data]: #user used to run server and write log - run_group [www-data]: + logs_directory [$((INSTALL))/var/log]: + run_user [www-data]: # user used to run server and write logs + run_group [www-data]: # group used to run server and write logs Select beaker_backend: 1 - redis 2 - memcached @@ -192,7 +182,7 @@ Choose from 1, 2, 3 [1]: db_host [127.0.0.1]: db_port [8100]: - db_name [pyams]: zeo_pyams # db_name created step 1 + db_name [pyams]: zeo_pyams # db_name created in step 1 db_username []: db_password []: zeo_realm [pyams]: @@ -225,7 +215,7 @@ - python3.5 bootstrap.py - ./bin/buildout -In the project *pyams* folder, execute *bootstrap.py*... +In the project's *pyams* folder, execute *bootstrap.py*: .. code-block:: bash @@ -235,7 +225,7 @@ Creating directory '/var/local/env/pyams/develop-eggs'. Generated script '/var/local/env/pyams/bin/buildout'. -...and then run *buildout* +And run final *buildout*: .. code-block:: bash @@ -243,6 +233,7 @@ .. note:: + Packages download, compilation and installation can easily take several minutes. Install errors are generally due to missing libraries development headers. @@ -267,15 +258,18 @@ Serving on http://0.0.0.0:6543 -Congrats PyAMS is running ! +Congrats: PyAMS is running ! Launch a browser and open URL http://127.0.0.1:6543/admin to get access to PyAMS management interface. -.. warning:: By default: +.. warning:: + + By default: - Login: admin + - Password: admin - You must change it as soon as possible! + **You must change it as soon as possible!**