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 0. Before starting

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

    15 

    16 Required packages

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

    18 

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

    20 

    21 .. note::

    22 

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

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

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

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

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

    28 

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

    30 

    31 On a Debian GNU/Linux:

    32 

    33 .. code-block:: bash

    34 

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

    36      $ 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

    39 

    40 

    41 Initialize virtual environment

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

    43 

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

    45 

    46 .. code-block:: bash

    47 

    48     $ mkdir /var/local/

    49     $ pip3 install virtualenv

    50     $ virtualenv --python=python3.5 env

    51     $ source env/bin/activate

    52 

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

    54 

    55 .. code-block:: bash

    56 

    57     (env)$ pip3.5 install cookiecutter

    58 

    59 

    60 1. Create ZODB

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

    62 

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

    64 

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

    66 

    67 .. note::

    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 

    83     pyams_release [latest]:

    84     project_name [ZEO_server]: ZEO_pyams

    85     project_slug [zeo_pyams]:

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

    87     run_user [zeo]: mylogin                   # current user ID

    88     run_group [zeo]: mygroup                  # current user group

    89     zeo_server_port [8100]:

    90     zeo_storage [pyams]:

    91     zeo_pack_report [root@localhost]: email@my-domain.com

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

    93 

    94     Your ZEO environment is initialized.

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

    96     - cd zeo_pyams

    97     - python3.5 bootstrap.py

    98     - ./bin/buildout

    99 

   100 

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

   102 

   103 .. code-block:: bash

   104 

   105     (env)$ cd zeo_pyams

   106 

   107     (env)$ python3.5 bootstrap.py

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

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

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

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

   112 

   113 

   114 And then run final *buildout*:

   115 

   116 .. code-block:: bash

   117 

   118     (env)$ ./bin/buildout

   119 

   120     Installing zodb.

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

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

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

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

   125     Installing zdaemon.

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

   127     Installing zeo_pyams.

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

   129 

   130 

   131 Start the ZEO server:

   132 

   133 .. code-block:: bash

   134 

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

   136 

   137     Password:

   138     . . .

   139     daemon process started, pid=26230

   140 

   141 

   142 2. Create application instance

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

   144 

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

   146 

   147 .. code-block:: bash

   148 

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

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

   151 

   152 

   153 .. tip:: Configuration

   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 PyAMS plugins like **Elasticsearch** but you must install related services on

   158        your own. See also :ref:`plugins`

   159 

   160 

   161 .. code-block:: bash

   162 

   163     pyams_release [latest]:

   164     project_name [PyAMS]:

   165     project_slug [pyams]:

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

   167     webapp_name [webapp]:

   168     webapp_port [6543]:

   169     eggs_directory [eggs]:

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

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

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

   173     Select beaker_backend:

   174         1 - redis

   175         2 - memcached

   176     Choose from 1, 2 [1]:

   177     beaker_server [127.0.0.1:6379]:

   178     Select db_type:

   179         1 - zeo

   180         2 - relstorage

   181         3 - newt

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

   183     db_host [127.0.0.1]:

   184     db_port [8100]:

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

   186     db_username []:

   187     db_password []:

   188     zeo_realm [pyams]:

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

   190     use_postgresql [True]: False

   191     use_oracle [False]:

   192     use_ldap [False]:

   193     use_elasticsearch [False]:

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

   195     elasticsearch_index [pyams]:

   196     create_elasticsearch_index [False]:

   197     define_elasticsearch_mappings [False]:

   198     smtp_server [localhost]:

   199     smtp_server_name [pyams]:

   200     pyams_scheduler [127.0.0.1:5555]:

   201     start_scheduler [True]:

   202     pyams_medias_converter [127.0.0.1:5556]:

   203     start_medias_converter [True]:

   204     pyams_es_indexer [127.0.0.1:5557]:

   205     start_es_indexer [False]:

   206     use_notifications [True]: False

   207     pyams_ws_notify [127.0.0.1:8081]:

   208     lexicon_languages [en:english fr:french]:

   209     extension_package []:

   210     need_pyams_gis [False]:

   211     Your server environment is initialized.

   212 

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

   214     - cd pyams

   215     - python3.5 bootstrap.py

   216     - ./bin/buildout

   217 

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

   219 

   220 .. code-block:: bash

   221 

   222     (env)$ cd pyams

   223     (env)$ python3.5 bootstrap.py

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

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

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

   227 

   228 And run final *buildout*:

   229 

   230 .. code-block:: bash

   231 

   232     (env)$ ./bin/buildout

   233 

   234 

   235 .. note::

   236 

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

   238     missing libraries development headers.

   239 

   240 

   241 .. tip::

   242 

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

   244 

   245 

   246 After *buildout*, just check INI files in *etc* directory (see :ref:`config`)

   247 

   248 

   249 3. Initializing the database

   250 ++++++++++++++++++++++++++++

   251 

   252 You have to initialize the database to populate **PyAMS** objects into database. From a shell:

   253 

   254 .. code-block:: bash

   255 

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

   257 

   258 

   259 4. Starting application

   260 +++++++++++++++++++++++

   261 

   262 Application is ready to run! Start the application:

   263 

   264 .. code-block:: bash

   265 

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

   267     ...

   268     Starting server in PID 29335.

   269     Serving on http://0.0.0.0:6543

   270 

   271 

   272 Congrats: PyAMS is running !

   273 

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

   275 

   276 .. image:: _static/pyams-login.png

   277 

   278 .. warning::

   279 

   280     By default:

   281 

   282     - Login: admin

   283     - Password: admin

   284 

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

   286     (see :ref:`pyams_security`)!!.