# HG changeset patch # User Damien Correia # Date 1521799250 -3600 # Node ID 7d77990df225d742cda18d56688fc5977bcef0ac # Parent c4d22fabf0179eae76ca79e46230500beae17127 Update Quickstart Documentation diff -r c4d22fabf017 -r 7d77990df225 src/source/quickstart.rst --- 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! +