mirror of
https://gitlab.com/Chill-Projet/chill-bundles.git
synced 2025-06-28 04:56:13 +00:00
Improve documentation for installation
This commit is contained in:
parent
f1e5ccd432
commit
81da34f1b6
GPG Key ID:
BDE2190974723FCB
95
README.md
95
README.md
@ -10,97 +10,6 @@ Chill-bundles is a set of bundles that should be used within a Symfony applicati
|
|||||||
|
|
||||||
A symfony application will help you to customize all the configuration options, change the behaviour of some parts of the usual-way that chill works, … without to have to fork this repository !
|
A symfony application will help you to customize all the configuration options, change the behaviour of some parts of the usual-way that chill works, … without to have to fork this repository !
|
||||||
|
|
||||||
### For a usage in production
|
See [the instructions in the docs](./docs/source/installation/index.rst).
|
||||||
|
|
||||||
You will create a symfony app, which will then download this bundle as a dependency.
|
Those instructions are also built [online](https://docs.chill.social).
|
||||||
|
|
||||||
See the documentation at https://docs.chill.social.
|
|
||||||
|
|
||||||
### 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 this repository and move to the cloned directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://gitlab.com/Chill-Projet/chill-bundles.git
|
|
||||||
cd chill-bundles
|
|
||||||
```
|
|
||||||
2. install depencies using composer
|
|
||||||
|
|
||||||
```bash
|
|
||||||
composer install
|
|
||||||
```
|
|
||||||
3. Install and compile assets:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
```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
|
|
||||||
|
|
||||||
```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 !
|
|
||||||
|
|
||||||
```bash
|
|
||||||
symfony console doctrine:fixtures:load
|
|
||||||
```
|
|
||||||
|
|
||||||
8. launch symfony dev-server
|
|
||||||
```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
|
|
||||||
|
|
||||||
```bash
|
|
||||||
symfony server:stop
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Restart the webserver for subsequent start
|
|
||||||
|
|
||||||
```bash
|
|
||||||
symfony server:start -d
|
|
||||||
# this will automatically starts the full docker compose services
|
|
||||||
```
|
|
||||||
|
|
||||||
## Documentation
|
|
||||||
|
|
||||||
The online documentation can be read at https://docs.chill.social, or the [`docs`][1] directory.
|
|
||||||
|
|
||||||
[1]: docs/README.md
|
|
||||||
|
|||||||
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
|
||||||
|
|
||||||
@ -17,6 +17,27 @@ Installation & Usage
|
|||||||
|
|
||||||
You will learn here how to install a new symfony project with chill, and configure it.
|
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
|
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
|
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.
|
information on how to run this without docker compose.
|
||||||
|
|
||||||
|
Instructions
|
||||||
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
|
|
||||||
=============
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
prod.rst
|
installation-development.rst
|
||||||
load-addresses.rst
|
installation-production.rst
|
||||||
prod-calendar-sms-sending.rst
|
|
||||||
msgraph-configure.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
|
||||||
Loading…
x
Reference in New Issue
Block a user