# HG changeset patch # User Thierry Florac # Date 1522053486 -7200 # Node ID a7332a53e6dc33108235f32fd27c4d3ba573650f # Parent c4d22fabf0179eae76ca79e46230500beae17127# Parent 4cddbff4269fff1f6e66c05a3cd2595f0987c1d1 Merge of 'dev-dc' branch and little updates diff -r c4d22fabf017 -r a7332a53e6dc buildout.cfg --- a/buildout.cfg Sun Mar 11 11:40:48 2018 +0100 +++ b/buildout.cfg Mon Mar 26 10:38:06 2018 +0200 @@ -93,6 +93,7 @@ recipe = collective.recipe.sphinxbuilder eggs = ${package:eggs} + sphinx_rtd_theme source = ${buildout:directory}/src/source build = ${buildout:directory}/src/build diff -r c4d22fabf017 -r a7332a53e6dc setup.py --- a/setup.py Sun Mar 11 11:40:48 2018 +0100 +++ b/setup.py Mon Mar 26 10:38:06 2018 +0200 @@ -62,6 +62,7 @@ extras_require=dict(test=tests_require), install_requires=[ 'setuptools', + 'sphinx_rtd_theme' # -*- Extra requirements: -*- ], entry_points={}) diff -r c4d22fabf017 -r a7332a53e6dc src/pyams_user_guide.egg-info/requires.txt --- a/src/pyams_user_guide.egg-info/requires.txt Sun Mar 11 11:40:48 2018 +0100 +++ b/src/pyams_user_guide.egg-info/requires.txt Mon Mar 26 10:38:06 2018 +0200 @@ -1,4 +1,5 @@ setuptools +sphinx_rtd_theme [test] pyramid_zcml diff -r c4d22fabf017 -r a7332a53e6dc src/source/conf.py --- a/src/source/conf.py Sun Mar 11 11:40:48 2018 +0100 +++ b/src/source/conf.py Mon Mar 26 10:38:06 2018 +0200 @@ -83,7 +83,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'pyramid' +html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff -r c4d22fabf017 -r a7332a53e6dc src/source/quickstart.rst --- a/src/source/quickstart.rst Sun Mar 11 11:40:48 2018 +0100 +++ b/src/source/quickstart.rst Mon Mar 26 10:38:06 2018 +0200 @@ -1,6 +1,6 @@ .. _quickstart: -PyAMS quickstart +PyAMS Quickstart ================ Here is a quick list of operations that you can follow to create and start your first PyAMS application from scratch. @@ -10,87 +10,113 @@ See :ref:`install` to get a full description of installation process. -To do first -+++++++++++ +0. Before starting +++++++++++++++++++ -PyAMS relies on Python packages for which you must have system packages available in your environment. These include: +Required packages +----------------- -* a C/C++ compiler (GCC is fine) +PyAMS relies on system and Python packages which you must have been previously installed in your environment. + +.. note:: -* a Python 3.5 interpreter with development headers; PyAMS may be compatible with other versions but has only been - completely tested with this version until now - -* several libraries with their development headers; these include libjpeg, libpng, libfreetype, libxml2 and libxslt - (and libpq if you want to use PostgreSQL) + - 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...). -* a cache server, like Redis or Memcached. +* PyAMS may be compatible with other versions but has only been completely tested with this version until now. -You can also choose to install Cython for better optimization of several packages... - -On a Debian GNU/Linux environment, required commands may be: +On a Debian GNU/Linux: .. code-block:: bash - # apt-get install python3.5 python3.5-dev - # apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev - # apt-get install redis-server redis-tools - # apt-get install cython3 + $ apt-get install python3.5 python3.5-dev + $ apt-get install cython3 + $ apt-get install redis-server redis-tools + $ apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev Initialize virtual environment -++++++++++++++++++++++++++++++ +------------------------------ + +We are creating a virtual environment in */var/local/env* + +.. code-block:: bash -We are creating a virtual environment in */var/local/env*; it will include a small set of utilities required to use -PyAMS templates: + $ mkdir /var/local/ + $ pip3 install virtualenv + $ virtualenv --python=python3.5 env + $ source env/bin/activate + +To use PyAMS templates, the *cookiecutter* tool is required: .. code-block:: bash - # mkdir /var/local/ - # pip3 install virtualenv - # virtualenv --python=python3.5 env - # cd env - # . bin/activate - (env) # pip3.5 install cookiecutter + (env)$ pip3.5 install cookiecutter -Create ZODB -+++++++++++ +1. Create ZODB +++++++++++++++ + +We are creating a local ZODB using a "ZEO server" cookiecutter template. + +.. tip:: To know more about ZODB storages you can see :ref:`zodb`. -We are creating a local ZODB using ZEO, based on PyAMS cookiecutter template; several configuration parameters -are required, Python eggs will be stored into */var/local/eggs* directory. +.. note:: -**WARNING**: in this quickstart example, ZEO server instance will run as current user and group; for a production -environment, it's better to use dedicated service user and group! + 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: .. code-block:: bash - (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server + (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server + + +Configuration: + +.. code-block:: bash + pyams_release [latest]: project_name [ZEO_server]: ZEO_pyams project_slug [zeo_pyams]: - eggs_directory [eggs]: /var/local/eggs - 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]: + logs_directory [/var/log/zeo/zeo_pyams]: # An absolute path is mandatory!!! Your ZEO environment is initialized. - To finalize it's creation, just type: + To finalize it\'s creation, just type: - cd zeo_pyams - python3.5 bootstrap.py - ./bin/buildout - (env) # cd zeo_pyams + +In *zeo_pyams* folder, execute *bootstrap.py*: - (env) # python3.5 bootstrap.py +.. code-block:: bash + + (env)$ cd zeo_pyams + + (env)$ python3.5 bootstrap.py Creating directory '/var/local/env/zeo_pyams/bin'. Creating directory '/var/local/env/zeo_pyams/parts'. Creating directory '/var/local/env/zeo_pyams/develop-eggs'. Generated script '/var/local/env/zeo_pyams/bin/buildout'. - (env) # ./bin/buildout + +And then run final *buildout*: + +.. code-block:: bash + + (env)$ ./bin/buildout + Installing zodb. Generated script '/var/local/env/zeo_pyams/bin/zeopack'. Generated script '/var/local/env/zeo_pyams/bin/runzeo'. @@ -101,49 +127,63 @@ Installing zeo_pyams. zc.zodbrecipes: Generated shell script '/var/local/env/zeo_pyams/etc/init.d/zeo-zeo_pyams'. - (env) # ./etc/init.d/zeo-zeo_pyams start + +Start the ZEO server: + +.. code-block:: bash + + (env)$ ./etc/init.d/zeo-zeo_pyams start + Password: - . + . . . daemon process started, pid=26230 -See :ref:`zodb` to know more about ZODB storage alternatives. - +2. Create application instance +++++++++++++++++++++++++++++++ -Create application instance -+++++++++++++++++++++++++++ - -Application instance is created in */var/local/env/pyams* via another template: +Application instance will be created in */var/local/env/pyams* via another coockiecutter template: .. code-block:: bash - (env) # cd /var/local/env + (env)$ cd /var/local/env + (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams + + +.. tip:: Configuration - (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams + 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 + pyams_release [latest]: project_name [PyAMS]: project_slug [pyams]: virtual_hostname [pyams.mydomain.com]: pyams.example.com webapp_name [webapp]: webapp_port [6543]: - eggs_directory [eggs]: /var/local/eggs - logs_directory [/var/log/apache2]: - run_user [www-data]: - run_group [www-data]: + eggs_directory [eggs]: + 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 + 1 - redis + 2 - memcached Choose from 1, 2 [1]: beaker_server [127.0.0.1:6379]: Select db_type: - 1 - zeo - 2 - relstorage - 3 - newt + 1 - zeo + 2 - relstorage + 3 - newt Choose from 1, 2, 3 [1]: db_host [127.0.0.1]: db_port [8100]: - db_name [pyams]: zeo_pyams - db_username [zeouser]: + db_name [pyams]: zeo_pyams # db_name created in step 1 + db_username []: db_password []: zeo_realm [pyams]: blobs_dir [$((INSTALL)/var/db/blobs]: @@ -169,43 +209,67 @@ extension_package []: need_pyams_gis [False]: Your server environment is initialized. - To finalize it's creation, just type: + + To finalize it\'s creation, just type: - cd pyams - python3.5 bootstrap.py - ./bin/buildout - (env) # cd pyams +In the project's *pyams* folder, execute *bootstrap.py*: - (env) # python3.5 bootstrap.py +.. code-block:: bash - (env) # ./bin/buildout + (env)$ cd pyams + (env)$ python3.5 bootstrap.py Creating directory '/var/local/env/pyams/bin'. Creating directory '/var/local/env/pyams/develop-eggs'. Generated script '/var/local/env/pyams/bin/buildout'. - (env) # ./bin/buildout - ... - (this may take some time!) +And run final *buildout*: -Packages download, compilation and installation can easily take several minutes. Install errors are generally due to -missing libraries development headers. +.. code-block:: bash -See :ref:`appinstall` to get more detailed information about installation process. + (env)$ ./bin/buildout -Start application +.. note:: + + Packages download, compilation and installation can easily take several minutes. Install errors are generally due to + missing libraries development headers. + + +.. tip:: + + See :ref:`appinstall` to get more detailed information about installation process. + + +3. Start application +++++++++++++++++ Application is ready to run! Just check INI files in *etc* directory (see :ref:`config`) and start the application: .. code-block:: bash - (env) # ./bin/pyams_upgrade etc/development.ini + (env)$ ./bin/pyams_upgrade etc/development.ini - (env) # ./bin/pserve etc/development.ini + (env)$ ./bin/pserve etc/development.ini ... Starting server in PID 29335. Serving on http://0.0.0.0:6543 -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! + +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: + + - Login: admin + + - Password: admin + + **You must change it as soon as possible!** +