3 PyAMS quickstart

     3 PyAMS Quickstart

    13 To do first

    13 0. Before starting

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

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

    15 

    15 

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

    16 Required packages

    17 

    17 -----------------

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

    18 

    19 

    19 PyAMS relies on system and Python packages which you must have been previously installed in your environment.

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

    20 

    21   completely tested with this version until now

    21 .. note::

    22 

    22 

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

    23     - a C/C++ compiler like **GCC**

    24   (and libpq if you want to use PostgreSQL)

    24     - **Python 3.5*** with development headers; **Cython3** for better optimization of several packages

    25 

    25     - a cache server, like **Redis** or **Memcached**.

    26 * a cache server, like Redis or Memcached.

    26     - Several libraries with their development headers: *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt*

    27 

    27       (and *libpq* if you want to use PostgreSQL, *libldap* if you want to use LDAP authentication...).

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

    28 

    29 

    29 * PyAMS may be compatible with other versions but has only been completely tested with this version until now.

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

    30 

    31 

    31 On a Debian GNU/Linux:

    32 .. code-block:: bash

    32 

    33 

    33 .. code-block:: bash

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

    34 

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

    35      $ apt-get install python3.5 python3.5-dev

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

    36      $ apt-get install cython3

    37     # apt-get install cython3

    37      $ apt-get install redis-server redis-tools

    38      $ apt-get install libjpeg-dev libpng-dev libfreetype6-dev libxml2-dev libxslt1-dev

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

    42 ------------------------------

    42 

    43 

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

    44 We are creating a virtual environment in */var/local/env*

    44 PyAMS templates:

    45 

    45 

    46 .. code-block:: bash

    46 .. code-block:: bash

    47 

    47 

    48     $ mkdir /var/local/

    48     # mkdir /var/local/

    49     $ pip3 install virtualenv

    49     # pip3 install virtualenv

    50     $ virtualenv --python=python3.5 env

    50     # virtualenv --python=python3.5 env

    51     $ source env/bin/activate

    51     # cd env

    52 

    52     # . bin/activate

    53 To use PyAMS templates, the *cookiecutter* tool is required:

    53     (env) # pip3.5 install cookiecutter

    54 

    54 

    55 .. code-block:: bash

    55 

    56 

    56 Create ZODB

    57     (env)$ pip3.5 install cookiecutter

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

    58 

    58 

    59 

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

    60 1. Create ZODB

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

    61 ++++++++++++++

    61 

    62 

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

    63 We are creating a local ZODB using a "ZEO server" cookiecutter template.

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

    64 

    64 

    65 .. tip:: To know more about ZODB storages you can see :ref:`zodb`.

    65 .. code-block:: bash

    66 

    66 

    67 .. note::

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

    68 

    69     In this example, ZEO server instance will run as current UNIX user and group. For a production

    70     environment, it's better to use dedicated service user and group.

    71 

    72 Run cookiecutter:

    73 

    74 .. code-block:: bash

    75 

    76     (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server

    77 

    78 

    79 Configuration:

    80 

    81 .. code-block:: bash

    82 

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

    86     eggs_directory [eggs]: /var/local/eggs    # Python eggs will be stored into */var/local/eggs* directory.

    72     run_user [zeo]: mylogin

    87     run_user [zeo]: mylogin                   # current user ID

    73     run_group [zeo]: mygroup

    88     run_group [zeo]: mygroup                  # current user group

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

    92     logs_directory [/var/log/zeo/zeo_pyams]:  # An absolute path is mandatory!!!

    80     To finalize it's creation, just type:

    95     To finalize it\'s creation, just type:

    85     (env) # cd zeo_pyams

   100 

    86 

   101 In *zeo_pyams* folder, execute *bootstrap.py*:

    87     (env) # python3.5 bootstrap.py

   102 

   103 .. code-block:: bash

   104 

   105     (env)$ cd zeo_pyams

   106 

   107     (env)$ python3.5 bootstrap.py

    93     (env) # ./bin/buildout

   113 

   114 And then run final *buildout*:

   115 

   116 .. code-block:: bash

   117 

   118     (env)$ ./bin/buildout

   119 

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

   130 

   131 Start the ZEO server:

   132 

   133 .. code-block:: bash

   134 

   135     (env)$ ./etc/init.d/zeo-zeo_pyams start

   136 

   106     .

   138     . . .

   110 See :ref:`zodb` to know more about ZODB storage alternatives.

   142 2. Create application instance

   111 

   143 ++++++++++++++++++++++++++++++

   112 

   144 

   113 Create application instance

   145 Application instance will be created in */var/local/env/pyams* via another coockiecutter template:

   114 +++++++++++++++++++++++++++

   146 

   115 

   147 .. code-block:: bash

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

   148 

   117 

   149     (env)$ cd /var/local/env

   118 .. code-block:: bash

   150     (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams

   119 

   151 

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

   152 

   121 

   153 .. tip:: Configuration

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

   154 

   155     1. The variable **$((INSTALL))** is the path to current folder; it will be replaced automatically by cookiecutter

   156        after application creation

   157     2. You will be invited to setup additional services like **Elasticsearch** but you must install them on

   158        your own.

   159 

   160 

   161 .. code-block:: bash

   162 

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

   169     eggs_directory [eggs]:

   130     logs_directory [/var/log/apache2]:

   170     logs_directory [$((INSTALL))/var/log]:

   131     run_user [www-data]:

   171     run_user [www-data]:      # user used to run server and write logs

   132     run_group [www-data]:

   172     run_group [www-data]:     # group used to run server and write logs

   134     1 - redis

   174         1 - redis

   135     2 - memcached

   175         2 - memcached

   139     1 - zeo

   179         1 - zeo

   140     2 - relstorage

   180         2 - relstorage

   141     3 - newt

   181         3 - newt

   145     db_name [pyams]: zeo_pyams

   185     db_name [pyams]: zeo_pyams  # db_name created in step 1

   146     db_username [zeouser]:

   186     db_username []:

   172     To finalize it's creation, just type:

   212 

   213     To finalize it\'s creation, just type:

   177     (env) # cd pyams

   218 In the project's *pyams* folder, execute *bootstrap.py*:

   178 

   219 

   179     (env) # python3.5 bootstrap.py

   220 .. code-block:: bash

   180 

   221 

   181     (env) # ./bin/buildout

   222     (env)$ cd pyams

   223     (env)$ python3.5 bootstrap.py

   186     (env) # ./bin/buildout

   228 And run final *buildout*:

   187     ...

   229 

   188     (this may take some time!)

   230 .. code-block:: bash

   189 

   231 

   190 Packages download, compilation and installation can easily take several minutes. Install errors are generally due to

   232     (env)$ ./bin/buildout

   191 missing libraries development headers.

   233 

   192 

   234 

   193 See :ref:`appinstall` to get more detailed information about installation process.

   235 .. note::

   194 

   236 

   195 

   237     Packages download, compilation and installation can easily take several minutes. Install errors are generally due to

   196 Start application

   238     missing libraries development headers.

   239 

   240 

   241 .. tip::

   242 

   243     See :ref:`appinstall` to get more detailed information about installation process.

   244 

   245 

   246 3. Start application

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

   253     (env)$ ./bin/pyams_upgrade etc/development.ini

   204 

   254 

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

   255     (env)$ ./bin/pserve etc/development.ini

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

   260 

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

   261 Congrats: PyAMS is running !

   262 

   263 Launch a browser and open URL http://127.0.0.1:6543/admin to get access to PyAMS management interface.

   264 

   265 

   266 .. warning::

   267 

   268     By default:

   269 

   270     - Login: admin

   271 

   272     - Password: admin

   273 

   274     **You must change it as soon as possible!**

   275