pyams/pyams_user_guide: comparison src/source/quickstart.rst

equal deleted inserted replaced

-:c4d22fabf017
+:7d77990df225
 .. _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.
 For this quick start, we will only use the most basic setup and keep several features disabled (like Elasticsearch
 integration, notifications...).
 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:
+**a. Package required**
-* a C/C++ compiler (GCC is fine)
-* a Python 3.5 interpreter with development headers; PyAMS may be compatible with other versions but has only been
+PyAMS relies on Python packages for which you must have system packages available in your environment.
-completely tested with this version until now
-* several libraries with their development headers; these include libjpeg, libpng, libfreetype, libxml2 and libxslt
+.. note::
-(and libpq if you want to use PostgreSQL)
+- C/C++ compiler like **GCC**
-* a cache server, like Redis or Memcached.
+- **Python 3.5*** with development headers or **Cython3** for better optimization of several packages
+- Cache server, like **Redis** or **Memcached**.
-You can also choose to install Cython for better optimization of several packages...
+- Several libraries with their development headers:
-On a Debian GNU/Linux environment, required commands may be:
+=> *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt* (and *libpq* if you want to use PostgreSQL)
-.. code-block:: bash
-# apt-get install python3.5 python3.5-dev
+*PyAMS may be compatible with other versions but has only been completely tested with this version until now
-# apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev
-# apt-get install redis-server redis-tools
+On a Debian GNU/Linux:
-# apt-get install cython3
+.. code-block:: bash
-Initialize virtual environment
+$ apt-get install python3.5 python3.5-dev
-++++++++++++++++++++++++++++++
+$ apt-get install cython3
+$ apt-get install redis-server redis-tools
-We are creating a virtual environment in */var/local/env*; it will include a small set of utilities required to use
+$ apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev
-PyAMS templates:
-.. code-block:: bash
+**b. Initialize virtual environment**
-# mkdir /var/local/
-# pip3 install virtualenv
+We are creating a virtual environment in */var/local/env*
-# virtualenv --python=python3.5 env
-# cd env
+.. code-block:: bash
-# . bin/activate
-(env) # pip3.5 install cookiecutter
+$ mkdir /var/local/
+$ pip3 install virtualenv
+$ virtualenv --python=python3.5 env
-Create ZODB
+$ source env/bin/activate
-+++++++++++
+To use PyAMS templates *cookiecutter* is required
-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.
+.. code-block:: bash
-**WARNING**: in this quickstart example, ZEO server instance will run as current user and group; for a production
+(env)$ pip3.5 install cookiecutter
-environment, it's better to use dedicated service user and group!
-.. code-block:: bash
+1. Create ZODB
-(env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server
+++++++++++++++
+We are creating a local ZODB using ZEO server using cookiecutter template
+.. tip:: To know more about ZODB storage you can see :ref:`zodb`.
+.. note::
+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
+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'.
 Generated script '/var/local/env/zeo_pyams/bin/zeo-nagios'.
 Generated script '/var/local/env/zeo_pyams/bin/zeoctl'.
 Installing zdaemon.
 Generated script '/var/local/env/zeo_pyams/bin/zdaemon'.
 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
+.. tip::
-(env) # cd /var/local/env
+.. code-block:: bash
-(env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
+(env)$ cd /var/local/env
+(env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
+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.
+.. 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
+eggs_directory [eggs]:
-logs_directory [/var/log/apache2]:
+logs_directory [ $((INSTALL))/var/log]:
-run_user [www-data]:
+run_user [www-data]:    #user used to run server and write log
 run_group [www-data]:
 Select beaker_backend:
 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
 Choose from 1, 2, 3 [1]:
 db_host [127.0.0.1]:
 db_port [8100]:
-db_name [pyams]: zeo_pyams
+db_name [pyams]: zeo_pyams  # db_name created step 1
-db_username [zeouser]:
+db_username []:
 db_password []:
 zeo_realm [pyams]:
 blobs_dir [$((INSTALL)/var/db/blobs]:
 use_postgresql [True]: False
 use_oracle [False]:
 pyams_ws_notify [127.0.0.1:8081]:
 lexicon_languages [en:english fr:french]:
 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
+...and then run *buildout*
-...
-(this may take some time!)
+.. code-block:: bash
-Packages download, compilation and installation can easily take several minutes. Install errors are generally due to
+(env)$ ./bin/buildout
-missing libraries development headers.
-See :ref:`appinstall` to get more detailed information about installation process.
+.. note::
+Packages download, compilation and installation can easily take several minutes. Install errors are generally due to
+missing libraries development headers.
-Start application
+.. 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!

branch	dev-dc
changeset 26	7d77990df225
parent 22	2dfb4161b66c
child 28	a7332a53e6dc