.. _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. 0. Requirement ++++++++++++++ Packages -------- PyAMS relies on system and Python packages which you must have been previously installed in your environment. .. note:: - a C/C++ compiler like **GCC** - **Python 3.5*** with development headers; **Cython3** for better optimization of several packages - a cache server, like **Redis** or **Memcached**. - Several libraries with their development headers: *libjpeg*, *libpng*, *libfreetype*, *libxml2* and *libxslt* (and *libpq* if you want to use PostgreSQL, *libldap* if you want to use LDAP authentication...). * 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 $ 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 Initialize virtual environment ------------------------------ We are creating a virtual environment in */var/local/env* .. code-block:: bash $ mkdir /var/local/ $ pip3 install virtualenv $ virtualenv --python=python3.5 env $ source env/bin/activate To use PyAMS templates, the *cookiecutter* tool is required: .. code-block:: bash (env)$ pip3.5 install cookiecutter 1. Creating Database ++++++++++++++++++++ Create ZODB ----------- We are creating a local ZODB using a "ZEO server" cookiecutter template. .. tip:: To know more about ZODB storages you can see :ref:`zodb`. .. note:: In this example, ZEO server instance will run as current 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 Configuration: .. code-block:: bash pyams_release [latest]: project_name [ZEO_server]: ZEO_pyams project_slug [zeo_pyams]: eggs_directory [eggs]: /var/local/eggs # Python eggs will be stored into */var/local/eggs* directory. run_user [zeo]: mylogin # current user ID run_group [zeo]: mygroup # current user group zeo_server_port [8100]: zeo_storage [pyams]: zeo_pack_report [root@localhost]: email@my-domain.com logs_directory [/var/log/zeo/zeo_pyams]: # An absolute path is mandatory!!! Your ZEO environment is initialized. To finalize it\'s creation, just type: - cd zeo_pyams - python3.5 bootstrap.py - ./bin/buildout Configuration ZODB ------------------ In *zeo_pyams* folder, execute *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'. And then run final *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'. 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'. Run ZODB server --------------- Start the ZEO server: .. code-block:: bash (env)$ ./etc/init.d/zeo-zeo_pyams start Password: . . . daemon process started, pid=26230 2. Creating application instance ++++++++++++++++++++++++++++++++ Application instance will be created in */var/local/env/pyams* via another coockiecutter template: .. code-block:: bash (env)$ cd /var/local/env (env)$ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams .. tip:: Configuration 1. The variable **$((INSTALL))** is the path to current folder; it will be replaced automatically by cookiecutter after application creation 2. You will be invited to setup additional PyAMS plugins like **Elasticsearch** but you must install related services on your own. See also :ref:`plugins` .. 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]: logs_directory [$((INSTALL))/var/log]: run_user [www-data]: # user used to run server and write logs run_group [www-data]: # group used to run server and write logs 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_name created in step 1 db_username []: 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 In the project's *pyams* folder, execute *bootstrap.py*: .. code-block:: bash (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'. And run final *buildout*: .. code-block:: bash (env)$ ./bin/buildout .. note:: Packages download, compilation and installation can easily take several minutes. Install errors are generally due to missing libraries development headers. .. tip:: See :ref:`install` to get more detailed information about installation process. After *buildout*, just check INI files in *etc* directory (see :ref:`config`) 3. Initializing the database ++++++++++++++++++++++++++++ You have to initialize the database to populate **PyAMS** objects into database. From a shell: .. code-block:: bash (env) $ ./bin/pyams_upgrade etc/development.ini 4. Starting application +++++++++++++++++++++++ Application is ready to run! Start the application: .. code-block:: bash (env)$ ./bin/pserve etc/development.ini ... Starting server in PID 29335. Serving on http://0.0.0.0:6543 Congrats: PyAMS is running ! Launch a browser and open URL http://127.0.0.1:6543/admin to get access to PyAMS management interface. .. image:: _static/pyams-login.png .. warning:: By default: - Login: admin - Password: admin **You must change it as soon as possible!** (see :ref:`pyams_security`)!!.