Mercurial Mercurial > pyams > pyams_user_guide / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/source/quickstart.rst
branchdev-dc
changeset 26 7d77990df225
parent 22 2dfb4161b66c
child 28 a7332a53e6dc 
--- a/src/source/quickstart.rst	Sun Mar 11 11:40:48 2018 +0100
+++ b/src/source/quickstart.rst	Fri Mar 23 11:00:50 2018 +0100
@@ -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,119 @@
 See :ref:`install` to get a full description of installation process.
 
 
-To do first
-+++++++++++
+0. Before starting
+++++++++++++++++++
+
+
+**a. Package required**
+
+
+PyAMS relies on Python packages for which you must have system packages available in your environment.
 
-PyAMS relies on Python packages for which you must have system packages available in your environment. These include:
+
+.. note::
 
-* a C/C++ compiler (GCC is fine)
+    - 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**.
+
+    - Several libraries with their development headers:
 
-* 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
+        => *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt* (and *libpq* if you want to use PostgreSQL)
+
 
-* several libraries with their development headers; these include 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
+
+On a Debian GNU/Linux:
+
+.. code-block:: bash
 
-* a cache server, like Redis or Memcached.
+     $ 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
 
-You can also choose to install Cython for better optimization of several packages...
+
+**b. Initialize virtual environment**
 
-On a Debian GNU/Linux environment, required commands may be:
+
+We are creating a virtual environment in */var/local/env*
 
 .. 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
-
+    $ mkdir /var/local/
+    $ pip3 install virtualenv
+    $ virtualenv --python=python3.5 env
+    $ source env/bin/activate
 
-Initialize virtual environment
-++++++++++++++++++++++++++++++
-
-We are creating a virtual environment in */var/local/env*; it will include a small set of utilities required to use
-PyAMS templates:
+To use PyAMS templates *cookiecutter* 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 ZEO server using cookiecutter template
+
+.. tip:: To know more about ZODB storage 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 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
+    eggs_directory [eggs]: /var/local/eggs  #Python eggs will be stored into */var/local/eggs* directory.
     run_user [zeo]: mylogin
     run_group [zeo]: mygroup
     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]:  #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 *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 +133,67 @@
     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.
 
 
-Create application instance
+2. 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:
+
+.. tip::
 
 .. code-block:: bash
 
-    (env) # cd /var/local/env
+    (env)$ cd /var/local/env
+    (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
+
+
+Configuration
 
-    (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
+.. 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.
+
+
+.. 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]:
+    eggs_directory [eggs]:
+    logs_directory [ $((INSTALL))/var/log]:
+    run_user [www-data]:    #user used to run server and write log
     run_group [www-data]:
     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 step 1
+    db_username []:
     db_password []:
     zeo_realm [pyams]:
     blobs_dir [$((INSTALL)/var/db/blobs]:
@@ -169,43 +219,63 @@
     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 *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 then run *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!
+
pyams/pyams_user_guide