chill-bundles/docs/source/installation/index.rst

.. chill-doc documentation master file, created by
   sphinx-quickstart on Sun Sep 28 22:04:08 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. Copyright (C)  2014-2019 Champs Libres Cooperative SCRLFS
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.3
   or any later version published by the Free Software Foundation;
   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   A copy of the license is included in the section entitled "GNU
   Free Documentation License".

Installation & Usage
####################


You will learn here how to install a new symfony project with chill, and configure it.

Requirements
============

The installation is tested on a Debian-like linux distribution. The installation on other operating systems is not documented.

You have to install the following tools on your computer:

- `PHP <https://www.php.net/>`_, version 8.3+, with the following extensions: pdo_pgsql, intl, mbstring, zip, bcmath, exif, sockets, redis, ast, gd;
- `composer <https://getcomposer.org/>`_;
- `symfony cli <https://symfony.com/download>`_;
- `node, we encourage you to use nvm to configure the correct version <https://github.com/nvm-sh/nvm>`_. The project contains an
  :code:`.nvmrc` file which selects automatically the required version of node (if present).
- `yarn <https://classic.yarnpkg.com/lang/en/docs/install/>`_. We use the version 1.22+ for now.
- `docker and the plugin compose <https://docker.com>`_ to run the database

Chill needs a redis server and a postgresql database, and a few other things like a "relatorio service" which will
generate documents from templates. **All these things are available through docker using the plugin compose**. We do not provide
information on how to run this without docker compose.


Install a new project
=====================

Initialize project and dependencies
***********************************

.. code-block:: bash

   symfony new --version=5.4 my_chill_project
   cd my_chill_project

We strongly encourage you to initialize a git repository at this step, to track further changes.

.. code-block:: bash

   # add the flex endpoints required for custom recipes
   cat <<< "$(jq '.extra.symfony += {"endpoint": ["flex://defaults", "https://gitlab.com/api/v4/projects/57371968/repository/files/index.json/raw?ref=main"]}' composer.json)" > composer.json
   # install chill and some dependencies
   # TODO fix the suffix "alpha1" and replace by ^3.0.0 when version 3.0.0 will be released
   symfony composer require chill-project/chill-bundles v3.0.0-alpha1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev

We encourage you to accept the inclusion of the "Docker configuration from recipes": this is the documented way to run the database.
You must also accept to configure recipes from the contrib repository, unless you want to configure the bundles manually).

.. code-block:: bash

   # fix some configuration
   ./post-install-chill.sh
   # install node dependencies
   yarn install
   # and compile assets
   yarn run encore production

.. note::

   If you encounter this error during assets compilation (:code:`yarn run encore production`) (repeated multiple times):

   .. code-block:: txt

      [tsl] ERROR in /tmp/chill/v1/public/bundles/chillcalendar/types.ts(2,65)
            TS2307: Cannot find module '../../../ChillMainBundle/Resources/public/types' or its corresponding type declarations.

   run:

   .. code-block:: bash

      rm -rf public/bundles/*

   Then restart the compilation of assets (:code:```yarn run encore production```)

Configure your project
**********************

You should read the configuration files in :code:`chill/config/packages` carefully, especially if you have
custom developments. But most of the time, this should be fine.

You have to configure some local variables, which are described in the :code:`.env` file. The secrets should not be stored
in this :code:`.env` file, but instead using the `secrets management tool <https://symfony.com/doc/current/configuration/secrets.html>`_
or in the :code:`.env.local` file, which should not be commited to the git repository.

You do not need to set variables for the smtp server, redis server and relatorio server, as they are generated automatically
by the symfony server, from the docker compose services.

The only required variable is the :code:`ADMIN_PASSWORD`. You can generate a hashed and salted admin password using the command
:code:`symfony console security:hash-password <your password> 'Symfony\Component\Security\Core\User\User'`. Then,
you can either:

- add this password to the :code:`.env.local` file, you must escape the character :code:`$`: if the generated password
  is :code:`$2y$13$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm`, your :code:`.env.local` file will be:

  .. code-block:: env

     ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm

- add the generated password to the secrets manager (**note**: you must add the generated hashed password to the secrets env,
  not the password in clear text).

Prepare migrations and other tools
**********************************

To continue the installation process, you will have to run migrations:

.. code-block:: bash

   # start databases and other services
   docker compose up -d
   # the first start, it may last some seconds, you can check with docker compose ps
   # run migrations
   symfony console doctrine:migrations:migrate
   # setup messenger
   symfony console messenger:setup-transports
   # prepare some views
   symfony console chill:db:sync-views

.. warning::

   If you encounter an error while running :code:`symfony console messenger:setup-transports`, you can set up the messenger
   transport to redis, by adding this in the :code:`.env.local` or :code:`.env` file:

   .. code-block:: env

      MESSENGER_TRANSPORT_DSN=redis://${REDIS_HOST}:${REDIS_PORT}/messages

Start your web server locally
*****************************

At this step, Chill will be ready to be served locally, but without any configuration. You can run the project
locally using the `local symfony server <https://symfony.com/doc/current/setup/symfony_server.html>`_:

.. code-block:: bash

   # see the whole possibilities at https://symfony.com/doc/current/setup/symfony_server.html
   symfony server:start -d


If you need to test the instance with accounts and some basic configuration, please install the fixtures (see below).


Add capabilities for dev
========================

If you need to add custom bundles, you can develop them in the `src/` directory, like for any other symfony project. You
can rely on the whole chill framework, meaning there is no need to add them to the original `chill-bundles`.

You will require some bundles to have the following development tools:

- add fixtures
- add profiler and var-dumper to debug

Install fixtures
****************

.. code-block:: bash

   # generate fixtures for chill
   symfony composer require --dev doctrine/doctrine-fixtures-bundle nelmio/alice
   # now, you can generate fixtures (this will reset your database)
   symfony console doctrine:fixtures:load

This will generate user accounts, centers, and some basic configuration.

The accounts created are: :code:`center a_social`, :code:`center b_social`, :code:`center a_direction`, ...  The full list is
visibile in the "users" table: :code:`docker compose exec database psql -U app -c "SELECT username FROM users"`.

The password is always :code:`password`.

.. warning::

   The fixtures are not fully functional. See the `corresponding issue <https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280>`_.

Add web profiler and debugger
*****************************

.. code-block:: bash

   symfony composer require --dev symfony/web-profiler-bundle symfony/var-dumper

Working on chill bundles
************************

If you plan to improve the chill-bundles repository, that's great!

You will have to download chill-bundles as a git repository (and not as an archive, which is barely editable).

In your :code:`composer.json` file, add these lines:

.. code-block:: diff

    {
        "config": {
   +        "preferred-install": {
   +            "chill-project/chill-bundles": "source",
                "*": "dist"
   +         }
        }

Then, run :code:`symfony composer reinstall chill-project/chill-bundles` to re-install the package from source.

Code style, code quality and other tools
****************************************

For development, you will also have to install:

- `php-cs-fixer <https://cs.symfony.com/>`_

We also encourage you to use tools like `phpstan <https://phpstan.org>`_ and `rector <https://getrector.com>`_.

Commit and share your project
=============================

If multiple developers work on a project, you can commit your symfony project and share it with other people.

When another developer clones your project, they will have to:

- run :code:`symfony composer install` and :code:`yarn install` to install the same dependencies as the initial developer;
- run :code:`yarn run encore production` to compile assets;
- copy any possible variables from the :code:`.env.local` files;
- start the docker compose stack, using :code:`docker compose`, and run migrations, set up transports, and prepare chill db views
  (see the corresponding command above)

Update
======

In order to update your app, you must update dependencies:

- for chill-bundles, you can `set the last version <https://gitlab.com/Chill-Projet/chill-bundles/-/releases>`_ manually
  in the :code:`composer.json` file, or set the version to `^3.0.0` and run :code:`symfony composer update` regularly
- run :code:`composer update` and :code:`yarn update` to maintain your dependencies up-to-date.

After each update, you must update your database schema:

.. code-block:: bash

   symfony console doctrine:migrations:migrate
   symfony console chill:db:sync-views

Operations
==========

Build assets
************

run those commands:

.. code-block:: bash

   # for production (or in dev, when you don't need to work on your assets and need some speed)
   yarn run encore production
   # in dev, when you wan't to reload the assets on each changes
   yarn run encore dev --watch

How to execute the console ?
****************************

.. code-block:: bash

   # start the console with all required variables
   symfony console
   # you can add your command after that:
   symfony console list

How to generate documents
*************************

Documents are generated asynchronously by `"consuming messages" <https://symfony.com/doc/current/messenger.html#consuming-messages-running-the-worker>`_.

You must generate them using a dedicated process:

.. code-block:: bash

   symfony console messenger:consume async priority

To avoid memory issues, we encourage you to also use the :code:`--limit` parameter of the command.

How to read emails sent by the program ?
*******************************************

In development, there is a built-in "mail catcher". Open it with :code:`symfony open:local:webmail`

How to run cron-jobs ?
**********************

Some commands must be executed in :ref:`cron jobs <cronjob>`. To execute them:

.. code-block:: bash

   symfony console chill:cron-job:execute

What about materialized views ?
*******************************

There are some materialized views in chill, to speed up some complex computations in the database.

In order to refresh them, run a cron job or refresh them manually in your database.

How to run tests for chill-bundles
**********************************

Tests reside inside the installed bundles. You must `cd` into that directory, download the required packages, and execute them from this place.

**Note**: some bundles require the fixtures to be executed. See the dedicated _how-tos_.

Example, for running a unit test inside `main` bundle:

.. code-block:: bash

   # cd into main directory
   cd vendor/chill-project/chill-bundles
   composer install
   # run tests
   bin/phpunit src/Bundle/path/to/your/test

Or for running tests to check code style and php conventions with csfixer and phpstan:

Troubleshooting
===============

Error `An exception has been thrown during the rendering of a template ("Asset manifest file "/var/www/app/web/build/manifest.json" does not exist.").` on first run
********************************************************************************************************************************************************************

Build assets, see above.

Running in production
=====================

Currently, to run this software in production, the *state of the art* is the following :

1. Run the software locally and tweak the configuration to your needs ;
2. Build the image and store it in a private container registry.

.. warning::

   In production, you **must** set these variables:

   * ``APP_ENV`` to ``prod``
   * ``APP_DEBUG`` to ``false``

   There are security issues if you keep the same variables as for production.


Going further
=============

.. toctree::
   :maxdepth: 2

   prod.rst
   load-addresses.rst
   prod-calendar-sms-sending.rst
   msgraph-configure.rst