.. _installation_guide/installation/framework_installation: Genropy installation ==================== Prerequisites ------------- Before proceeding with these instructions please make sure you have installed correctly in your development environment: - `Git `_ - `Python `_ - `pip `_ You can find tips and advice on the installation process for these prerequisites in the :ref:`appendix` of this guide. .. hint:: It is recommended to always have the latest version of **pip** available. You can upgrade with the command:: python3 -m pip install --upgrade pip Genropy versions ---------------- There are currently two branches of Genropy: - **master** is the stable and recommended version, in Python3 - **develop** is the development branch, where it is possible to test new features before they are made available on the main branch .. hint:: There is also currently a no longer updated *legacy* branch **py2**, which is compatible with Python 2 but which we recommend abandoning. The *master* and *develop* branches prior to the release of the new installation mode were tagged as follows: - **master-pre-243** is the *legacy* version of the master branch as of early March 2024, which uses the old installation procedure - **develop-pre-243** is the *legacy* version of the develop branch as of early March 2024, which uses the old installation procedure For those who want to go back to the old installation mode, you can checkout with these tags. Creating the development directory ---------------------------------- The next one is an optional step, but before starting we suggest you to create a *directory* where we will clone the Genropy repository and that will be the default location for all future projects. In this guide we will be using the name ``development``, but feel free to change it as you prefer; next, position yourself inside it from within the terminal window. :: mkdir development cd development Cloning the Genropy project --------------------------- Now we need to clone the project using the command:: git clone https://github.com/genropy/genropy.git At this point you should find the ``genropy`` directory, containing all the source files for the project up to the last update. Run the installation -------------------- After cloning the repository, you can enter the ``genropy/gnrpy`` folder:: cd genropy/gnrpy and automatically install the libraries required by Genropy by running the command:: sudo pip install . .. hint:: If you are installing Genropy in virtualenv you can omit *sudo*. Four installation profiles are available, depending on your needs: - ``pgsql`` - for use with PostgreSQL databases - ``mysql`` - for use with MySQL databases - ``sqlite`` - for use with SqLite databases - ``developer`` - to install a set of extra tools useful for developing with Genropy Installing one or more profiles will allow you to install all the necessary dependencies. To specify the desired profiles use the syntax:: sudo pip install --editable ".[pgsql,developer]" .. hint:: The ``--editable`` attribute is not mandatory, but it allows you to create a link to the current folder instead of installing the files. In this way, by *pulling* the repository it will be possible to perform the updates from time to time without having to re-execute the pip install referred to in the previous point. This is **best practice for developers** in the testing environment. Initialization ---------------- At this point the installation is completed, but to be able to start creating Genropy projects it is necessary to run a script that initializes the development environment. We run the command:: gnr app initgenropy The script creates an ``admin`` user with a random generated password that you should use to access local applications only. Write down the password and follow the instructions in the output text to change the password, if required. The following message should appear in the terminal window: .. code :: Default password for user admin is ****, you can change it by editing /../../.gnr/instanceconfig/default.xml The script `initgenropy.py` creates some files and directories needed to properly run Genropy: - the ``.gnr`` directory, containing the default configuration file for the development environment - the ``genropy_projects`` directory, the place where you will be keeping your projects if you choose to keep the :ref:`default configuration` .. hint :: On Windows OS, the directory containing the configuration files is called ``gnr`` and not ``.gnr`` and will still be placed inside the user's *home folder*, `C:\\users\\\\gnr` Additional information can be found in the :ref:`appendix on environment configurations` To verify that you have correctly installed and configured the Genropy development environment, you can continue reading the section about our simple :ref:`test application` . Keeping the project up-to-date ------------------------------ Now that you have cloned the project to your local folder, you can keep your Genropy installation up to date by running the following command from the ``genropy`` directory:: git pull .. hint:: If you installed with the ``--editable`` attribute you do not need to perform any additional steps. Otherwise, after *pulling* the repository it will be necessary to repeat the *pip install .* procedure to synchronize files and libraries. .. sectionauthor:: Davide Paci