--- 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
--- 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={})
--- 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
--- 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
--- 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!**
+