diff -r 1d12ff3f036a -r ba0b83b57c0c src/source/quickstart.rst --- /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!