mirror of
https://gitlab.com/Chill-Projet/chill-bundles.git
synced 2025-08-20 14:43:49 +00:00
Merge master into translations branch
This commit is contained in:
34
docs/source/development/code-quality.rst
Normal file
34
docs/source/development/code-quality.rst
Normal file
@@ -0,0 +1,34 @@
|
||||
Code style, code quality and other tools
|
||||
########################################
|
||||
|
||||
PHP-cs-fixer
|
||||
============
|
||||
|
||||
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>`_.
|
||||
|
||||
For running php-cs-fixer:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symfony composer php-cs-fixer
|
||||
|
||||
Execute tests
|
||||
=============
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symfony composer exec phpunit -- /path/to_your_test.php
|
||||
|
||||
Note that IDE like PhpStorm should be able to run tests, even KernelTestcase or WebTestCase, `from within their interfaces <https://www.jetbrains.com/help/phpstorm/using-phpunit-framework.html#run_phpunit_tests>`_.
|
||||
|
||||
Execute rector
|
||||
==============
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
symfony composer exec rector -- process
|
||||
|
||||
@@ -39,9 +39,12 @@ Implements a :code:`Chill\MainBundle\Cron\CronJobInterface`. Here is an example:
|
||||
use Chill\MainBundle\Entity\CronJobExecution;
|
||||
use DateInterval;
|
||||
use DateTimeImmutable;
|
||||
use Symfony\Component\Clock\ClockInterface;
|
||||
|
||||
class MyCronJob implements CronJobInterface
|
||||
{
|
||||
function __construct(private ClockInterface $clock) {}
|
||||
|
||||
public function canRun(?CronJobExecution $cronJobExecution): bool
|
||||
{
|
||||
// the parameter $cronJobExecution contains data about the last execution of the cronjob
|
||||
@@ -56,7 +59,7 @@ Implements a :code:`Chill\MainBundle\Cron\CronJobInterface`. Here is an example:
|
||||
|
||||
// this cron job should be executed if the last execution is greater than one day, but only during the night
|
||||
|
||||
$now = new DateTimeImmutable('now');
|
||||
$now = $clock->now();
|
||||
|
||||
return $cronJobExecution->getLastStart() < $now->sub(new DateInterval('P1D'))
|
||||
&& in_array($now->format('H'), self::ACCEPTED_HOURS, true)
|
||||
@@ -69,10 +72,15 @@ Implements a :code:`Chill\MainBundle\Cron\CronJobInterface`. Here is an example:
|
||||
return 'arbitrary-and-unique-key';
|
||||
}
|
||||
|
||||
public function run(): void
|
||||
public function run(array $lastExecutionData): void
|
||||
{
|
||||
// here, we execute the command
|
||||
}
|
||||
|
||||
// we return execution data, which will be served for next execution
|
||||
// this data should be easily serializable in a json column: it should contains
|
||||
// only int, string, etc. Avoid storing object
|
||||
return ['last-execution-id' => 0];
|
||||
}
|
||||
}
|
||||
|
||||
How are cron job scheduled ?
|
||||
|
||||
125
docs/source/installation/enable-collabora-for-dev.rst
Normal file
125
docs/source/installation/enable-collabora-for-dev.rst
Normal file
@@ -0,0 +1,125 @@
|
||||
|
||||
Enable CODE for development
|
||||
===========================
|
||||
|
||||
For editing a document, there must be a way to communicate between the collabora server and the symfony server, in
|
||||
both direction. The domain name should also be the same for collabora server and for the browser which access to the
|
||||
online editor.
|
||||
|
||||
Using ngrok (or other http tunnel)
|
||||
----------------------------------
|
||||
|
||||
One can configure a tunnel server to expose your local install to the web, and access to your local server using the
|
||||
tunnel url.
|
||||
|
||||
Start ngrok
|
||||
^^^^^^^^^^^
|
||||
|
||||
This can be achieve using `ngrok <https://ngrok.com/>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The configuration of ngrok is outside of the scope of this document. Refers to the ngrok's documentation.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# ensuring that your server is running through http and port 8000
|
||||
ngrok http 8000
|
||||
# then open the link given by the ngrok utility and you should reach your app
|
||||
|
||||
At this step, ensure that you can reach your local app using the ngrok url.
|
||||
|
||||
Configure Collabora
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The collabora server must be executed online and configure to access to your ngrok installation. Ensure that the aliasgroup
|
||||
exists for your ngrok application (`See the CODE documentation: <https://sdk.collaboraonline.com/docs/installation/Configuration.html#multihost-configuration>`_).
|
||||
|
||||
Configure your app
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Set the :code:`EDITOR_SERVER` variable to point to your collabora server, this should be done in your :code:`.env.local` file.
|
||||
|
||||
At this point, everything must be fine. In case of errors, watch the log from your collabora server, use the `profiler <https://symfony.com/doc/current/profiler.html>`_
|
||||
to debug the requests.
|
||||
|
||||
.. note::
|
||||
|
||||
In case of error while validating proof (you'll see those message in the collabora's logs), you can temporarily disable
|
||||
the proof validation adding this code snippet in `config/services.yaml`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
when@dev:
|
||||
# add only in dev environment, to avoid security problems
|
||||
services:
|
||||
ChampsLibres\WopiLib\Contract\Service\ProofValidatorInterface:
|
||||
# this class will always validate proof
|
||||
alias: Chill\WopiBundle\Service\Wopi\NullProofValidator
|
||||
|
||||
With a local CODE image
|
||||
-----------------------
|
||||
|
||||
.. warning::
|
||||
|
||||
This configuration is not sure, and must be refined. The documentation does not seems to be entirely valid.
|
||||
|
||||
Use a local domain name and https for your app
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use the proxy feature from embedded symfony server to run your app. `See the dedicated doc <https://symfony.com/doc/current/setup/symfony_server.html#local-domain-names>`
|
||||
|
||||
Configure also the `https certificate <https://symfony.com/doc/current/setup/symfony_server.html#enabling-tls>`_
|
||||
|
||||
In this example, your local domain name will be :code:`my-domain` and the url will be :code:`https://my-domain.wip`.
|
||||
|
||||
Ensure that the proxy is running.
|
||||
|
||||
Create a certificate database for collabora
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Collabora must validate your certificate generated by symfony console. For that, you need `to create a NSS database <https://sdk.collaboraonline.com/docs/installation/Configuration.html#validating-digital-signatures>`
|
||||
and configure collabora to use it.
|
||||
|
||||
At first, export the certificate for symfony development. Use the graphical interface from your browser to get the
|
||||
certificate as a PEM file.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# create your database in a custom directory
|
||||
mkdir /path/to/your/directory
|
||||
certutil -N -d /path/to/your/directory
|
||||
cat /path/to/your/ca.crt | certutil -d . -A symfony -t -t C,P,C,u,w -a
|
||||
|
||||
Launch CODE properly configured
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
collabora:
|
||||
image: collabora/code:latest
|
||||
environment:
|
||||
- SLEEPFORDEBUGGER=0
|
||||
- DONT_GEN_SSL_CERT="True"
|
||||
# add path to the database
|
||||
- extra_params=--o:ssl.enable=false --o:ssl.termination=false --o:logging.level=7 -o:certificates.database_path=/etc/custom-certificates/nss-database
|
||||
- username=admin
|
||||
- password=admin
|
||||
- dictionaries=en_US
|
||||
- aliasgroup1=https://my-domain.wip
|
||||
ports:
|
||||
- "127.0.0.1:9980:9980"
|
||||
volumes:
|
||||
- "/path/to/your/directory/nss-database:/etc/custom-certificates/nss-database"
|
||||
extra_hosts:
|
||||
- "my-domain.wip:host-gateway"
|
||||
|
||||
Configure your app
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Into your :code:`.env.local` file:
|
||||
|
||||
.. code-block:: env
|
||||
|
||||
EDITOR_SERVER=http://${COLLABORA_HOST}:${COLLABORA_PORT}
|
||||
|
||||
At this step, you should be able to edit a document through collabora.
|
||||
@@ -17,6 +17,27 @@ Installation & Usage
|
||||
|
||||
You will learn here how to install a new symfony project with chill, and configure it.
|
||||
|
||||
Which can of installation do I need ?
|
||||
=====================================
|
||||
|
||||
I want to run chill in production
|
||||
---------------------------------
|
||||
|
||||
See the :ref:`instructions about installing Chill for production <installation-production>`.
|
||||
|
||||
I want to add features to the main chill bundles
|
||||
------------------------------------------------
|
||||
|
||||
If you want to add features to chill bundles itself, **and** you want those features to be merged into the chill bundles,
|
||||
you can use the "development" installation mode.
|
||||
|
||||
See the :ref:`instruction for installation for development <installation-for-dev>`.
|
||||
|
||||
I want to add features to Chill, but keep those features for my instance
|
||||
-------------------------------------------------------------------------
|
||||
|
||||
Follow the same instruction than for production, until the end.
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
@@ -36,341 +57,11 @@ Chill needs a redis server and a postgresql database, and a few other things lik
|
||||
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-RC3 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 committed 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
|
||||
# note: if you copy-paste the line above, the password will be "admin".
|
||||
|
||||
- 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).
|
||||
|
||||
- set up the jwt authentication bundle
|
||||
|
||||
Some environment variables are available for the JWT authentication bundle in the :code:`.env` file.
|
||||
|
||||
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
|
||||
# generate jwt token, required for some api features (webdav access, ...)
|
||||
symfony console lexik:jwt:generate-keypair
|
||||
|
||||
.. 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 debug bundle
|
||||
|
||||
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
|
||||
visible 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/debug-bundle
|
||||
|
||||
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
|
||||
=============
|
||||
Instructions
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
prod.rst
|
||||
load-addresses.rst
|
||||
prod-calendar-sms-sending.rst
|
||||
msgraph-configure.rst
|
||||
installation-development.rst
|
||||
installation-production.rst
|
||||
|
||||
101
docs/source/installation/installation-development.rst
Normal file
101
docs/source/installation/installation-development.rst
Normal file
@@ -0,0 +1,101 @@
|
||||
.. _installation-for-dev:
|
||||
|
||||
Installation for development or testing purpose only
|
||||
====================================================
|
||||
|
||||
⚠️ Use this method for development only. ⚠️
|
||||
|
||||
You will need:
|
||||
|
||||
- `Composer <https://getcomposer.org>`__;
|
||||
- `Symfony-cli tool <https://symfony.com/download>`__;
|
||||
- `docker <https://docs.docker.com/engine/install/>`__ and
|
||||
`docker-compose <https://docs.docker.com/compose/>`__
|
||||
- node > 20 and yarn 1.22
|
||||
|
||||
First initialization
|
||||
--------------------
|
||||
|
||||
1. clone the repository and move to the cloned directory:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone https://gitlab.com/Chill-Projet/chill-bundles.git
|
||||
cd chill-bundles
|
||||
|
||||
2. install dependencies using composer
|
||||
|
||||
.. code:: bash
|
||||
|
||||
composer install
|
||||
|
||||
3. Install and compile assets:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
yarn install
|
||||
yarn run encore production
|
||||
|
||||
**note** double check that you have the node version > 20 using the
|
||||
``node --version`` command.
|
||||
|
||||
4. configure your project: create a ``.env.local`` file at the root, and
|
||||
add the admin password:
|
||||
|
||||
.. code:: dotenv
|
||||
|
||||
# for this installation mode, the environment should always be "dev"
|
||||
APP_ENV=dev
|
||||
ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm
|
||||
# note: if you copy-paste the line above, the password will be "admin".
|
||||
|
||||
5. start the stack using ``docker compose up -d``, check the status of
|
||||
the start with ``docker compose ps``
|
||||
|
||||
6. configure all the needed third-party tools
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# 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
|
||||
# generate jwt token, required for some api features (webdav access, ...)
|
||||
symfony console lexik:jwt:generate-keypair
|
||||
|
||||
7. add some fixtures
|
||||
|
||||
This will truncate all the existing data of the database. But remember,
|
||||
we are in dev mode !
|
||||
|
||||
.. code:: bash
|
||||
|
||||
symfony console doctrine:fixtures:load
|
||||
|
||||
8. launch symfony dev-server
|
||||
|
||||
.. code:: bash
|
||||
|
||||
symfony server:start -d
|
||||
|
||||
And visit the web page it suggest. You can login with user
|
||||
``center a_social`` and password ``password``, or login ``admin`` with
|
||||
the password you set.
|
||||
|
||||
Stopping the server
|
||||
-------------------
|
||||
|
||||
.. code:: bash
|
||||
|
||||
symfony server:stop
|
||||
|
||||
Restart the webserver for subsequent start
|
||||
------------------------------------------
|
||||
|
||||
.. code:: bash
|
||||
|
||||
symfony server:start -d
|
||||
# this will automatically starts the full docker compose services
|
||||
328
docs/source/installation/installation-production.rst
Normal file
328
docs/source/installation/installation-production.rst
Normal file
@@ -0,0 +1,328 @@
|
||||
.. _installation-production:
|
||||
|
||||
Install Chill for production with or without adding personal features
|
||||
#####################################################################
|
||||
|
||||
Chill is a set of "bundles" for a symfony app.
|
||||
|
||||
To run Chill in production or add new features to it (without merging those features to the chill core), you must create
|
||||
a symfony app, and eventually add those features into your app.
|
||||
|
||||
Once you are happy with the configuration, `you should follow the dedicated instructions of how to go into production for
|
||||
Symfony apps <https://symfony.com/doc/current/deployment.html>`_.
|
||||
|
||||
Install a new app
|
||||
=================
|
||||
|
||||
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-RC3 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 committed 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
|
||||
# note: if you copy-paste the line above, the password will be "admin".
|
||||
|
||||
- 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).
|
||||
|
||||
- set up the jwt authentication bundle
|
||||
|
||||
Some environment variables are available for the JWT authentication bundle in the :code:`.env` file.
|
||||
|
||||
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
|
||||
# generate jwt token, required for some api features (webdav access, ...)
|
||||
symfony console lexik:jwt:generate-keypair
|
||||
|
||||
.. 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 debug bundle
|
||||
|
||||
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
|
||||
visible 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/debug-bundle
|
||||
|
||||
Working on chill bundles
|
||||
------------------------
|
||||
|
||||
If you plan to improve the chill-bundles repository, that's great!
|
||||
|
||||
It would be better :ref:`to follow the instruction about development <installation-for-dev>`. But if those features are
|
||||
deeply linked to some dev you made in the app, it can be easier to develop within the :code:`vendor/` directory.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Go to 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
|
||||
Reference in New Issue
Block a user