--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/quickstart.rst Mon Jan 15 16:47:26 2018 +0100
@@ -0,0 +1,203 @@
+.. _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
++++++++++++
+
+PyAMS relies on Python packages for which you must have system packages available in your environment. These include:
+
+* 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
+ 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 cache server, like Redis or Memcached.
+
+You can also choose to install Cython for better optimization of several packages...
+
+On a Debian GNU/Linux environment, required commands may be:
+
+.. 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
+
+
+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:
+
+.. code-block:: bash
+
+ # mkdir /var/local/
+ # pip3 install virtualenv
+ # virtualenv --python=python3.5 env
+ # cd env
+ # . bin/activate
+ (env) # pip3.5 install cookiecutter
+
+
+Create 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.
+
+**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!
+
+.. code-block:: bash
+
+ (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server
+ 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
+ zeo_server_port [8100]:
+ zeo_storage [zeo_pyams]: pyams
+ zeo_pack_report [root@localhost]:
+ logs_directory [/var/log/zeo/zeo_pyams]:
+
+ Your ZEO environment is initialized.
+ To finalize it's creation, just type:
+ - cd zeo_pyams
+ - python3.5 bootstrap.py
+ - ./bin/buildout
+
+ (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
+ 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
+ Password:
+ .
+ daemon process started, pid=26230
+
+
+Create application instance
++++++++++++++++++++++++++++
+
+Application instance is created in */var/local/env/pyams* via another template:
+
+.. code-block:: bash
+
+ (env) # cd /var/local/env
+
+ (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
+ 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]:
+ 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_username [zeouser]:
+ db_password []:
+ zeo_realm [pyams]:
+ blobs_dir [$((INSTALL)/var/db/blobs]:
+ use_postgresql [True]: False
+ use_oracle [False]:
+ use_ldap [False]:
+ use_elasticsearch [False]:
+ elasticsearch_server [http://127.0.0.1:9200]:
+ elasticsearch_index [pyams]:
+ create_elasticsearch_index [False]:
+ define_elasticsearch_mappings [False]:
+ smtp_server [localhost]:
+ smtp_server_name [pyams]:
+ pyams_scheduler [127.0.0.1:5555]:
+ start_scheduler [True]:
+ pyams_medias_converter [127.0.0.1:5556]:
+ start_medias_converter [True]:
+ pyams_es_indexer [127.0.0.1:5557]:
+ start_es_indexer [False]:
+ use_notifications [True]: 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:
+ - cd pyams
+ - python3.5 bootstrap.py
+ - ./bin/buildout
+
+ (env) # cd pyams
+
+ (env) # python3.5 bootstrap.py
+
+ (env) # ./bin/buildout
+ 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!)
+
+
+Start application
++++++++++++++++++
+
+Application is ready to run! Just check INI files in *etc* directory and start the application:
+
+.. code-block:: bash
+
+ (env) # ./bin/pyams_upgrade 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!