1 .. _quickstart:

     2 

     3 PyAMS quickstart

     4 ================

     5 

     6 Here is a quick list of operations that you can follow to create and start your first PyAMS application from scratch.

     7 For this quick start, we will only use the most basic setup and keep several features disabled (like Elasticsearch

     8 integration, notifications...).

     9 

    10 See :ref:`install` to get a full description of installation process.

    11 

    12 

    13 To do first

    14 +++++++++++

    15 

    16 PyAMS relies on Python packages for which you must have system packages available in your environment. These include:

    17 

    18 * a C/C++ compiler (GCC is fine)

    19 

    20 * a Python 3.5 interpreter with development headers; PyAMS may be compatible with other versions but has only been

    21   completely tested with this version until now

    22 

    23 * several libraries with their development headers; these include libjpeg, libpng, libfreetype, libxml2 and libxslt

    24   (and libpq if you want to use PostgreSQL)

    25 

    26 * a cache server, like Redis or Memcached.

    27 

    28 You can also choose to install Cython for better optimization of several packages...

    29 

    30 On a Debian GNU/Linux environment, required commands may be:

    31 

    32 .. code-block:: bash

    33 

    34     # apt-get install python3.5 python3.5-dev

    35     # apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev

    36     # apt-get install redis-server redis-tools

    37     # apt-get install cython3

    38 

    39 

    40 Initialize virtual environment

    41 ++++++++++++++++++++++++++++++

    42 

    43 We are creating a virtual environment in */var/local/env*; it will include a small set of utilities required to use

    44 PyAMS templates:

    45 

    46 .. code-block:: bash

    47 

    48     # mkdir /var/local/

    49     # pip3 install virtualenv

    50     # virtualenv --python=python3.5 env

    51     # cd env

    52     # . bin/activate

    53     (env) # pip3.5 install cookiecutter

    54 

    55 

    56 Create ZODB

    57 +++++++++++

    58 

    59 We are creating a local ZODB using ZEO, based on PyAMS cookiecutter template; several configuration parameters

    60 are required, Python eggs will be stored into */var/local/eggs* directory.

    61 

    62 **WARNING**: in this quickstart example, ZEO server instance will run as current user and group; for a production

    63 environment, it's better to use dedicated service user and group!

    64 

    65 .. code-block:: bash

    66 

    67     (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server

    68     pyams_release [latest]:

    69     project_name [ZEO_server]: ZEO_pyams

    70     project_slug [zeo_pyams]:

    71     eggs_directory [eggs]: /var/local/eggs

    72     run_user [zeo]: mylogin

    73     run_group [zeo]: mygroup

    74     zeo_server_port [8100]:

    75     zeo_storage [zeo_pyams]: pyams

    76     zeo_pack_report [root@localhost]:

    77     logs_directory [/var/log/zeo/zeo_pyams]:

    78 

    79     Your ZEO environment is initialized.

    80     To finalize it's creation, just type:

    81     - cd zeo_pyams

    82     - python3.5 bootstrap.py

    83     - ./bin/buildout

    84 

    85     (env) # cd zeo_pyams

    86 

    87     (env) # python3.5 bootstrap.py

    88     Creating directory '/var/local/env/zeo_pyams/bin'.

    89     Creating directory '/var/local/env/zeo_pyams/parts'.

    90     Creating directory '/var/local/env/zeo_pyams/develop-eggs'.

    91     Generated script '/var/local/env/zeo_pyams/bin/buildout'.

    92 

    93     (env) # ./bin/buildout

    94     Installing zodb.

    95     Generated script '/var/local/env/zeo_pyams/bin/zeopack'.

    96     Generated script '/var/local/env/zeo_pyams/bin/runzeo'.

    97     Generated script '/var/local/env/zeo_pyams/bin/zeo-nagios'.

    98     Generated script '/var/local/env/zeo_pyams/bin/zeoctl'.

    99     Installing zdaemon.

   100     Generated script '/var/local/env/zeo_pyams/bin/zdaemon'.

   101     Installing zeo_pyams.

   102     zc.zodbrecipes: Generated shell script '/var/local/env/zeo_pyams/etc/init.d/zeo-zeo_pyams'.

   103 

   104     (env) # ./etc/init.d/zeo-zeo_pyams start

   105     Password:

   106     .

   107     daemon process started, pid=26230

   108 

   109 

   110 Create application instance

   111 +++++++++++++++++++++++++++

   112 

   113 Application instance is created in */var/local/env/pyams* via another template:

   114 

   115 .. code-block:: bash

   116 

   117     (env) # cd /var/local/env

   118 

   119     (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams

   120     pyams_release [latest]:

   121     project_name [PyAMS]:

   122     project_slug [pyams]:

   123     virtual_hostname [pyams.mydomain.com]: pyams.example.com

   124     webapp_name [webapp]:

   125     webapp_port [6543]:

   126     eggs_directory [eggs]: /var/local/eggs

   127     logs_directory [/var/log/apache2]:

   128     run_user [www-data]:

   129     run_group [www-data]:

   130     Select beaker_backend:

   131     1 - redis

   132     2 - memcached

   133     Choose from 1, 2 [1]:

   134     beaker_server [127.0.0.1:6379]:

   135     Select db_type:

   136     1 - zeo

   137     2 - relstorage

   138     3 - newt

   139     Choose from 1, 2, 3 [1]:

   140     db_host [127.0.0.1]:

   141     db_port [8100]:

   142     db_name [pyams]: zeo_pyams

   143     db_username [zeouser]:

   144     db_password []:

   145     zeo_realm [pyams]:

   146     blobs_dir [$((INSTALL)/var/db/blobs]:

   147     use_postgresql [True]: False

   148     use_oracle [False]:

   149     use_ldap [False]:

   150     use_elasticsearch [False]:

   151     elasticsearch_server [http://127.0.0.1:9200]:

   152     elasticsearch_index [pyams]:

   153     create_elasticsearch_index [False]:

   154     define_elasticsearch_mappings [False]:

   155     smtp_server [localhost]:

   156     smtp_server_name [pyams]:

   157     pyams_scheduler [127.0.0.1:5555]:

   158     start_scheduler [True]:

   159     pyams_medias_converter [127.0.0.1:5556]:

   160     start_medias_converter [True]:

   161     pyams_es_indexer [127.0.0.1:5557]:

   162     start_es_indexer [False]:

   163     use_notifications [True]: False

   164     pyams_ws_notify [127.0.0.1:8081]:

   165     lexicon_languages [en:english fr:french]:

   166     extension_package []:

   167     need_pyams_gis [False]:

   168     Your server environment is initialized.

   169     To finalize it's creation, just type:

   170     - cd pyams

   171     - python3.5 bootstrap.py

   172     - ./bin/buildout

   173 

   174     (env) # cd pyams

   175 

   176     (env) # python3.5 bootstrap.py

   177 

   178     (env) # ./bin/buildout

   179     Creating directory '/var/local/env/pyams/bin'.

   180     Creating directory '/var/local/env/pyams/develop-eggs'.

   181     Generated script '/var/local/env/pyams/bin/buildout'.

   182 

   183     (env) # ./bin/buildout

   184     ...

   185     (this may take some time!)

   186 

   187 

   188 Start application

   189 +++++++++++++++++

   190 

   191 Application is ready to run! Just check INI files in *etc* directory and start the application:

   192 

   193 .. code-block:: bash

   194 

   195     (env) # ./bin/pyams_upgrade etc/development.ini

   196 

   197     (env) # ./bin/pserve etc/development.ini

   198     ...

   199     Starting server in PID 29335.

   200     Serving on http://0.0.0.0:6543

   201 

   202 Launch a browser and open URL *http://127.0.0.1:6543/admin* to get access to PyAMS management interface; default

   203 login is "admin/admin", that you may change as soon as possible!