Chill-project/chill-bundles
6
0
Fork 0
mirror of https://gitlab.com/Chill-Projet/chill-bundles.git synced 2025-11-23 04:17:45 +00:00
Code Issues Actions Projects Releases Wiki Activity

Change all content from rst format to markdown and correct spelling/grammar

Browse Source
This commit is contained in:
Julie Lenaerts
2025-11-17 16:06:13 +01:00
parent c647648e84
commit 21f196218d
87 changed files with 3973 additions and 3441 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/source/installation/document-storage.md Normal file
View File

@@ -0,0 +1,74 @@
# Document storage
You can store a document in two different ways:
- on disk
- in the cloud, using object storage: currently only [openstack swift ](https://docs.openstack.org/api-ref/object-store/index.html) is supported.
## Comparison
Storing documents within the cloud is particularly suitable for "portable" deployments, like in kubernetes, or within a container
without having to manage volumes to store documents. But you'll have to subscribe to a commercial offer.
Storing documents on disk is easier to configure but more challenging to manage: if you use container, you will have to
manager volumes to attach documents on disk. You'll have to do some backup of the directory. If chill is load-balanced (and
multiple instances of chill are run), you will have to find a way to share the directories in read-write mode for every instance.
## On Disk
Configure Chill like this:
```yaml
# file config/packages/chill_doc_store.yaml
chill_doc_store:
use_driver: local_storage
local_storage:
storage_path: '%kernel.project_dir%/var/storage'
```
In this configuration, documents will be stored in [var/storage` within your app directory. But this path can be
elsewhere on the disk. Be aware that the directory must be writable by the user executing the chill app (php-fpm or www-data).
Documents will be stored in subpathes within that directory. The files will be encrypted, the key is stored in the database.
# In the cloud, using openstack object store
You must subscribe to a commercial offer for an object store.
Chill uses some features to allow documents to be stored in the cloud without being uploaded first to the chill server:
- `Form POST Middelware ](https://docs.openstack.org/swift/latest/api/form_post_middleware.html);
- [Temporary URL Middelware ](https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html).
A secret key must be generated and configured, and CORS must be configured depending on the domain you will use to serve Chill.
At first, create a container and get the base path to the container. For instance, on OVH, if you create a container named "mychill",
you will be able to retrieve the base path of the container within the OVH interface, like this:
- base_path: [https://storage.gra.cloud.ovh.net/v1/AUTH_123456789/mychill/` => will be variable `ASYNC_UPLOAD_TEMP_URL_BASE_PATH`
- container: `mychill` => will be variable `ASYNC_UPLOAD_TEMP_URL_CONTAINER`
You can also generate a key, which should have at least 20 characters. This key will go in the variable `ASYNC_UPLOAD_TEMP_URL_KEY`.
See the `documentation of symfony ](https://symfony.com/doc/current/configuration.html#config-env-vars) on how to store variables, and how to encrypt them if needed.
Configure the storage like this:
```yaml
# file config/packages/chill_doc_store.yaml
chill_doc_store:
use_driver: openstack
openstack:
temp_url:
temp_url_key: '%env(resolve:ASYNC_UPLOAD_TEMP_URL_KEY)%' # Required
container: '%env(resolve:ASYNC_UPLOAD_TEMP_URL_CONTAINER)%' # Required
temp_url_base_path: '%env(resolve:ASYNC_UPLOAD_TEMP_URL_BASE_PATH)%' # Required
```
Chill is able to configure the container to store a document. Grab an Openstack Token (for instance, using `openstack token issue` or
the web interface of your openstack provider), and run this command:
`symfony console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example`
# or, without symfony-cli
`bin/console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example`

84
docs/source/installation/document-storage.rst
View File

@@ -1,84 +0,0 @@
Document storage
################
You can store document on two different ways:
- on disk
- in the cloud, using object storage: currently only `openstack swift <https://docs.openstack.org/api-ref/object-store/index.html>`_ is supported.
Comparison
==========
Storing documents within the cloud is particularily suitable for "portable" deployments, like in kubernetes, or within container
without having to manage volumes to store documents. But you'll have to subscribe on a commercial offer.
Storing documents on disk is more easy to configure, but more difficult to manage: if you use container, you will have to
manager volumes to attach documents on disk. You'll have to do some backup of the directory. If chill is load-balanced (and
multiple instances of chill are run), you will have to find a way to share the directories in read-write mode for every instance.
On Disk
=======
Configure Chill like this:
.. code-block:: yaml
# file config/packages/chill_doc_store.yaml
chill_doc_store:
use_driver: local_storage
local_storage:
storage_path: '%kernel.project_dir%/var/storage'
In this configuration, documents will be stored in :code:`var/storage` within your app directory. But this path can be
elsewhere on the disk. Be aware that the directory must be writable by the user executing the chill app (php-fpm or www-data).
Documents will be stored in subpathes within that directory. The files will be encrypted, the key is stored in the database.
In the cloud, using openstack object store
##########################################
You must subscribe to a commercial offer for object store.
Chill use some features to allow documents to be stored in the cloud without being uploaded first to the chill server:
- `Form POST Middelware <https://docs.openstack.org/swift/latest/api/form_post_middleware.html>`_;
- `Temporary URL Middelware <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html>`_.
A secret key must be generated and configured, and CORS must be configured depending on the domain you will use to serve Chill.
At first, create a container and get the base path to the container. For instance, on OVH, if you create a container named "mychill",
you will be able to retrieve the base path of the container within the OVH interface, like this:
- base_path: :code:`https://storage.gra.cloud.ovh.net/v1/AUTH_123456789/mychill/` => will be variable :code:`ASYNC_UPLOAD_TEMP_URL_BASE_PATH`
- container: :code:`mychill` => will be variable :code:`ASYNC_UPLOAD_TEMP_URL_CONTAINER`
You can also generate a key, which should have at least 20 characters. This key will go in the variable :code:`ASYNC_UPLOAD_TEMP_URL_KEY`.
.. note::
See the `documentation of symfony <https://symfony.com/doc/current/configuration.html#config-env-vars>`_ on how to store variables, and how to encrypt them if needed.
Configure the storage like this:
.. code-block:: yaml
# file config/packages/chill_doc_store.yaml
chill_doc_store:
use_driver: openstack
openstack:
temp_url:
temp_url_key: '%env(resolve:ASYNC_UPLOAD_TEMP_URL_KEY)%' # Required
container: '%env(resolve:ASYNC_UPLOAD_TEMP_URL_CONTAINER)%' # Required
temp_url_base_path: '%env(resolve:ASYNC_UPLOAD_TEMP_URL_BASE_PATH)%' # Required
Chill is able to configure the container in order to store document. Grab an Openstack Token (for instance, using :code:`openstack token issue` or
the web interface of your openstack provider), and run this command:
.. code-block:: bash
symfony console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example
# or, without symfony-cli
bin/console async-upload:configure --os_token=OPENSTACK_TOKEN -d https://mychill.mydomain.example

103
docs/source/installation/enable-collabora-for-dev.md Normal file
View File

@@ -0,0 +1,103 @@
## 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 directions. 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 installation to the web and access to your local server using the
tunnel url.
##### Start ngrok
This can be achieved using [ngrok ](https://ngrok.com/).
The configuration of ngrok is outside the scope of this document. Refers to the ngrok's documentation.
# 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 configured 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 [EDITOR_SERVER` variable to point to your collabora server, this should be done in your `.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.
In case of error while validating proof (you'll see those messages in the collabora's logs), you can temporarily disable
the proof validation adding this code snippet in `config/services.yaml`:
```yaml
when@dev:
# add only in the 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
This configuration is not sure and must be refined. The documentation does not seem entirely valid.
##### Use a local domain name and https for your app
Use the proxy feature from the 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 `my-domain` and the url will be `https://my-domain.wip`.
Ensure that the proxy is running.
##### Create a certificate database for collabora
Collabora must validate your certificate generated by the 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.
# 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
```yaml
collabora:
image: collabora/code:latest
environment:
- SLEEPFORDEBUGGER=0
- DONT_GEN_SSL_CERT="True"
# add a 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
In your `.env.local` file:
`EDITOR_SERVER=http://${COLLABORA_HOST}:${COLLABORA_PORT}`
At this step, you should be able to edit a document through collabora.

125
docs/source/installation/enable-collabora-for-dev.rst
View File

@@ -1,125 +0,0 @@
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.

43
docs/source/installation/index.md Normal file
View File

@@ -0,0 +1,43 @@
# Installation & Usage
You will learn here how to install a new symfony project with chill, and configure it.
## Which kind of installation do I need?
### I want to run chill in production
See the [instructions about installing Chill for production ](installation-production.md).
### 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 [instruction for installation for development ](installation-for-dev.md).
### 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
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 a
`nvmrc` file which selects automatically the required version of node (if present).
- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/): We use 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.
## Instructions
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)

67
docs/source/installation/index.rst
View File

@@ -1,67 +0,0 @@
.. 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.
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
============
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.
Instructions
============
.. toctree::
:maxdepth: 2
installation-development.rst
installation-production.rst

77
docs/source/installation/installation-development.md Normal file
View File

@@ -0,0 +1,77 @@
## 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:
git clone https://gitlab.com/Chill-Projet/chill-bundles.git
cd chill-bundles
2. install dependencies using composer
composer install
3. Install and compile assets:
yarn install
yarn run encore production
**note** double-check that you have the node version > 20 using the
``node --version`` command.
1. configure your project: create a ``.env.local`` file at the root, and
add the admin password:
# 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".
2. start the stack using ``docker compose up -d``, check the status of
the start with ``docker compose ps``
3. configure all the necessary third-party tools
` # 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`
4. add some fixtures
This will truncate all the existing data of the database. But remember,
we are in dev mode!
symfony console doctrine:fixtures:load
5. launch symfony dev-server
`symfony server:start -d`
And visit the web page it suggests. You can log in with user
`center a_social` and password `password`, or login `admin` with
the password you set.
### Stopping the server
`symfony server:stop`
### Restart the webserver for a later start
`symfony server:start -d`
# this will automatically start the full docker compose services

101
docs/source/installation/installation-development.rst
View File

@@ -1,101 +0,0 @@
.. _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

287
docs/source/installation/installation-production.md Normal file
View File

@@ -0,0 +1,287 @@
# 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
### Install required dependencies:
- `jq`: https://jqlang.org/ (install it through your package manager);
- `php`, minimal version: 8.3;
- `composer`: https://getcomposer.org/download/
- `symfony-cli`: https://symfony.com/download
- `docker` with the plugin `compose`: https://docs.docker.com/engine/install/ and https://docs.docker.com/compose/install/
### Initialize the project and it's dependencies
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.
# 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
`symfony composer require -W chill-project/chill-bundles ^3.7.1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev symfony/amqp-messenger`
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).
` # fix some configuration
./post-install-chill.sh
# populate the cache for the first time. This is necessary to dump some translation files, required for the asset compilation
symfony console cache:clear
# install node dependencies
yarn install
# and compile assets
yarn run encore production`
If you encounter this error during asset compilation ([yarn run encore production`) (repeated multiple times):
```bash
[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:
```bash
rm -rf public/bundles/*
```
Then restart the compilation of assets (```yarn run encore production```)
### Configure your project
You should read the configuration files in `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 `.env` file. The secrets should not be stored
in this `.env` file, but instead using the `secrets management tool ](https://symfony.com/doc/current/configuration/secrets.html)
or in the `.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 required variables are:
- the `ADMIN_PASSWORD`;
- the `OVHCLOUD_DSN` variable;
##### `ADMIN_PASSWORD`
You can generate a hashed and salted admin password using the command: `symfony console security:hash-password <your password> 'Symfony\Component\Security\Core\User\User'[.Then,
you can either:
- add this password to the `.env.local` file, you must escape the character `$`: if the generated password
is `$2y$13$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm`, your `.env.local` file will be:
```bash
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).
##### `OVHCLOUD_DSN` and sending SMS messages
This is a temporary dependency, for ensuring compatibility for previous behaviour.
You can set it to `null://null` if you do not plan to use sending SMS.
OVHCLOUD_DSN=null://null
If you plan to do it, you can configure the notifier component `as described in the symfony documentation ](https://symfony.com/doc/current/notifier.html#notifier-sms-channel).
Some environment variables are available for the JWT authentication bundle in the [.env` file.
### Prepare database, messenger queue, and other configuration
To continue the installation process, you will have to run migrations:
# 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
# load languages data
symfony console chill:main:languages:populate
# generate jwt token, required for some api features (webdav access, ...)
symfony console lexik:jwt:generate-keypair
If you encounter this error:
```
No transport supports the given Messenger DSN.
```
Please check that you installed the package `symfony/amqp-messenger`.
### 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):
# 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
# 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: `center a_social`, `center b_social`, `center a_direction`, ... The full list is
visible in the "users" table: `docker compose exec database psql -U app -c "SELECT username FROM users"`.
The password is always `password`.
The fixtures are not fully functional. See the `corresponding issue ](https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280).
### Add web profiler and debugger
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 [to follow the instruction about development ](installation-for-dev.md). But if those features are
deeply linked to some dev you made in the app, it can be easier to develop within the [vendor/` directory.
You will have to download chill-bundles as a git repository (and not as an archive, which is barely editable).
In your `composer.json` file, add these lines:
{
"config": {
+ "preferred-install": {
+ "chill-project/chill-bundles": "source",
"*": "dist"
+ }
}
Then, run `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 [composer.json` file, or set the version to `^3.0.0` and run `symfony composer update` regularly
- run `composer update` and `yarn update` to maintain your dependencies up-to-date.
After each update, you must update your database schema:
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 `symfony composer install` and `yarn install` to install the same dependencies as the initial developer;
- run `yarn run encore production` to compile assets;
- copy any possible variables from the `.env.local` files;
- start the docker compose stack, using `docker compose`, and run migrations, set up transports, and prepare chill db views
(see the corresponding command above)
## Operations
### Build assets
run those commands:
` # 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 want to reload the assets on each changes
yarn run encore dev --watch`
### How to execute the console ?
` # 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:
symfony console messenger:consume async priority
To avoid memory issues, we encourage you to also use the `--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 `symfony open:local:webmail`
### How to run cron-jobs ?
Some commands must be executed in [cron jobs ](cronjob.md). To execute them:
`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.
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
- [Production Setup](prod.md)
- [Document Storage](document-storage.md)
- [Load Addresses](load-addresses.md)
- [Production Calendar SMS Sending](prod-calendar-sms-sending.md)
- [Microsoft Graph Configuration](msgraph-configure.md)

365
docs/source/installation/installation-production.rst
View File

@@ -1,365 +0,0 @@
.. _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
=================
Install required dependencies:
------------------------------
- `jq`: https://jqlang.org/ (install it through your package manager);
- `php`, minimal version: 8.3;
- `composer`: https://getcomposer.org/download/
- `symfony-cli`: https://symfony.com/download
- `docker` with the plugin `compose`: https://docs.docker.com/engine/install/ and https://docs.docker.com/compose/install/
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
symfony composer require -W chill-project/chill-bundles ^3.7.1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev symfony/amqp-messenger
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
# populate the cache for the first time. This is necessary to dump some translation files, required for the assets compilation
symfony console cache:clear
# 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::
[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 required variables are:
- the :code:`ADMIN_PASSWORD`;
- the :code:`OVHCLOUD_DSN` variable;
: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:: bash
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).
:code:`OVHCLOUD_DSN` and sending SMS messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is a temporary dependency, for ensuring compatibility for previous behaviour.
You can set it to :code:`null://null` if you do not plan to use sending SMS.
.. code-block:: bash
OVHCLOUD_DSN=null://null
If you plan to do it, you can configure the notifier component `as described in the symfony documentation <https://symfony.com/doc/current/notifier.html#notifier-sms-channel>`_.
Some environment variables are available for the JWT authentication bundle in the :code:`.env` file.
Prepare database, messenger queue, and other configuration
----------------------------------------------------------
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
# load languages data
symfony console chill:main:languages:populate
# generate jwt token, required for some api features (webdav access, ...)
symfony console lexik:jwt:generate-keypair
.. note::
If you encounter this error:
.. code-block::
No transport supports the given Messenger DSN.
Please check that you installed the package `symfony/amqp-messenger`.
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
document-storage.rst
load-addresses.rst
prod-calendar-sms-sending.rst
msgraph-configure.rst

47
docs/source/installation/load-addresses.md Normal file
View File

@@ -0,0 +1,47 @@
###### Addresses
Chill can store a list of geolocated address references, which are used to suggest address and ensure that the data is correctly stored.
Those addresses may be loaded from a dedicated source.
## Countries
To load addresses into the chill application we first have to make sure that a list of countries is present.
To import, the countries run the following command.
bin/console chill:main:countries:populate
## In France
The address is loaded from the [BANO ](https://bano.openstreetmap.fr/). The postal codes are loaded from [the official list of
postal codes ](https://datanova.laposte.fr/explore/dataset/laposte_hexasmal/information/)
# first, load postal codes
`bin/console chill:main:postal-code:load:FR`
# then, load all addresses by departement (multiple departements can be loaded by repeating the departement code
`bin/console chill:main:address-ref-from-bano 57 54 51`
## In Belgium
Addresses are prepared from the [BeST Address data ](https://www.geo.be/catalog/details/ca0fd5c0-8146-11e9-9012-482ae30f98d9).
Postal code is loaded from this database. There is no need to load postal codes from another source (actually, this is strongly discouraged).
The data are prepared for Chill ([See this repository ](https://gitea.champs-libres.be/Chill-project/belgian-bestaddresses-transform/releases)).
One can select postal code by his first number (`1xxx` for postal codes from 1000 to 1999), or a limited list for development purpose.
The command expects a language code as the first argument.
# load postal code from 1000 to 3999:
`bin/console chill:main:address-ref-from-best-addresse fr 1xxx 2xxx 3xxx`
# load only an extract (for dev purposes)
`bin/console chill:main:address-ref-from-best-addresse fr extract`
# load full addresses (discouraged)
`bin/console chill:main:address-ref-from-best-addresse fr full`
There is a possibility to load the full list of addresses is discouraged: the loading is optimized with smaller extracts.
Once you load the full list, it is not possible to load a smaller extract: each extract loaded **after** will not
delete the addresses loaded with the full extract (and some addresses will be present twice).

62
docs/source/installation/load-addresses.rst
View File

@@ -1,62 +0,0 @@
.. _addresses:
Addresses
*********
Chill can store a list of geolocated address references, which are used to suggest address and ensure that the data is correctly stored.
Those addresses may be load from a dedicated source.
Countries
=========
In order to load addresses into the chill application we first have to make sure that a list of countries is present.
To import the countries run the following command.
.. code-block:: bash
bin/console chill:main:countries:populate
In France
=========
The address are loaded from the `BANO <https://bano.openstreetmap.fr/>`_. The postal codes are loaded from `the official list of
postal codes <https://datanova.laposte.fr/explore/dataset/laposte_hexasmal/information/>`_
.. code-block:: bash
# first, load postal codes
bin/console chill:main:postal-code:load:FR
# then, load all addresses, by departement (multiple departement can be loaded by repeating the departement code
bin/console chill:main:address-ref-from-bano 57 54 51
In Belgium
==========
Addresses are prepared from the `BeST Address data <https://www.geo.be/catalog/details/ca0fd5c0-8146-11e9-9012-482ae30f98d9>`_.
Postal code are loaded from this database. There is no need to load postal codes from another source (actually, this is strongly discouraged).
The data are prepared for Chill (`See this repository <https://gitea.champs-libres.be/Chill-project/belgian-bestaddresses-transform/releases>`_).
One can select postal code by his first number (:code:`1xxx` for postal codes from 1000 to 1999), or a limited list for development purpose.
The command expects a language code as first argument.
.. code-block:: bash
# load postal code from 1000 to 3999:
bin/console chill:main:address-ref-from-best-addresse fr 1xxx 2xxx 3xxx
# load only an extract (for dev purposes)
bin/console chill:main:address-ref-from-best-addresse fr extract
# load full addresses (discouraged)
bin/console chill:main:address-ref-from-best-addresse fr full
.. note::
There is a possibility to load the full list of addresses is discouraged: the loading is optimized with smaller extracts.
Once you load the full list, it is not possible to load smaller extract: each extract loaded **after** will not
delete the addresses loaded with the full extract (and some addresses will be present twice).

161
docs/source/installation/msgraph-configure.rst → docs/source/installation/msgraph-configure.md
View File

@@ -1,70 +1,53 @@
Configure Chill for calendar and absence synchronisation and SSO with Microsoft Graph (Outlook)
===============================================================================================
## Configure Chill for calendar and absence synchronisation and SSO with Microsoft Graph (Outlook)
Chill offers the possibility to:
* authenticate users using Microsoft Graph, with relatively small adaptations;
* synchronize calendar in both ways (`see the user manual for a large description of the feature <https://gitea.champs-libres.be/Chill-project/manuals>`_).
* synchronize calendar in both ways ([see the user manual for a large description of the feature ](https://gitea.champs-libres.be/Chill-project/manuals)).
Both can be configured separately (synchronising calendars without SSO, or SSO without calendar).
Both can be configured separately (synchronising calendars without SSO, or SSO without a calendar).
Please note that the user's email address is the key to associate Chill's users with Microsoft's ones.
Configure SSO
-------------
### Configure SSO
On Azure side
*************
###### On the Azure side
Configure an app with the Azure interface, and give it the name of your choice.
Configure an app with the Azure interface and give it the name of your choice.
Grab the tenant's ID for your app, which is visible on the main tab "Vue d'ensemble":
.. figure:: ./saml_login_id_general.png
This is the variable which will be named `SAML_IDP_APP_UUID`.
This the variable which will be named :code:`SAML_IDP_APP_UUID`.
Go to the "Single sign-on" ("Authentication unique") section. Choose "SAML" as a protocol and fill those values:
Go to the "Single sign-on" ("Authentication unique") section. Choose "SAML" as protocol, and fill those values:
1. The `entityId` seems to be arbitrary. This will be your variable `SAML_ENTITY_ID`;
2. The url response must be your Chill's URL appended by `/saml/acs`
3. The only used attributes is `emailaddress`, which must match the user's email one.
.. figure:: ./saml_login_1.png
You must download the certificate, as base64. The format for the download is `cer`: you will remove the first and last line (the ones with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`), and remove all the return line. The final result should be something as `MIIAbcdef...XyZA=`.
1. The :code:`entityId` seems to be arbitrary. This will be your variable :code:`SAML_ENTITY_ID`;
2. The url response must be your Chill's URL appended by :code:`/saml/acs`
3. The only used attributes is :code:`emailaddress`, which must match the user's email one.
.. figure:: ./saml_login_2.png
You must download the certificate, as base64. The format for the download is :code:`cer`: you will remove the first and last line (the ones with :code:`-----BEGIN CERTIFICATE-----` and :code:`-----END CERTIFICATE-----`), and remove all the return line. The final result should be something as :code:`MIIAbcdef...XyZA=`.
This certificat will be your :code:`SAML_IDP_X509_CERT` variable.
This certificat will be your `SAML_IDP_X509_CERT` variable.
The url login will be filled automatically with your tenant id.
Do not forget to provider user's accesses to your app, using the "Utilisateurs et groupes" tab:
Remember to provider user's access to your app, using the "Utilisateurs et groupes" tab:
.. figure:: ./saml_login_appro.png
You must know have gathered all the required variables for SSO:
.. code-block::
You must now have gathered all the required variables for SSO:
SAML_BASE_URL=https://test.chill.be # must be
SAML_ENTITY_ID=https://test.chill.be # must match the one entered
SAML_IDP_APP_UUID=42XXXXXX-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SAML_IDP_X509_CERT: MIIC...E8u3bk # truncated
Configure chill app
*******************
###### Configure chill app
* add the bundle :code:`hslavich/oneloginsaml-bundle`
* add the bundle `hslavich/oneloginsaml-bundle`
* add the configuration file (see example above)
* configure the security part (see example above)
* add a user SAML factory into your src, and register it
.. code-block:: yaml
```yaml
# config/packages/hslavich_onelogin.yaml
@@ -74,7 +57,6 @@ Configure chill app
saml_idp_x509cert: '%env(resolve:SAML_IDP_X509_CERT)%'
saml_idp_app_uuid: '%env(resolve:SAML_IDP_APP_UUID)%'
hslavich_onelogin_saml:
# Basic settings
idp:
@@ -124,16 +106,14 @@ Configure chill app
name: 'Example'
displayname: 'Example'
url: 'http://example.com'
```
.. code-block:: yaml
```yaml
# config/security.yaml
# merge this with other existing configurations
security:
providers:
saml_provider:
# Loads user from user repository
@@ -143,7 +123,6 @@ Configure chill app
firewalls:
default:
# saml part:
saml:
@@ -158,10 +137,9 @@ Configure chill app
login_path: saml_login
logout:
path: /saml/logout
```
.. code-block:: php
```php
// src/Security/SamlFactory.php
namespace App\Security;
@@ -185,105 +163,87 @@ Configure chill app
return $user;
}
}
```
Configure sync and calendar access
----------------------------------
### Configure sync and calendar access
The purpose of this configuration is the following:
- let user read their calendar and shared calendar within Chill (with the same permissions as the one configured in Outlook / Azure);
- allow chill instance to write appointment ("Rendez-vous") into their calendar, and invite other users to their appointment;
- allow chill instance to be notified if an appoint is added or removed by the user within another interface than Chill: if the appointment match another one created in the Chill interface, the date and time are updated in Chill;
- allow chill instance to write appointment ("Rendez-vous") into their calendar and invite other users to their appointment;
- allow chill instance to be notified if an appointment is added or removed by the user within another interface than Chill: if the appointment matches another one created in the Chill interface, the date and time are updated in Chill;
- allow chill instance to read the absence of the user and, if set, mark the user as absent in Chill;
The sync processe might be configured in the same app, or into a different app on the Azure side.
The sync process might be configured in the same app, or into a different app on the Azure side.
The synchronization processes use Oauth 2.0 / OpenID Connect for authentication and authorization.
.. note::
Two flows are in use:
* we authenticate "on behalf of a user", to allow users to see their own calendar or other user's calendar into the web interface.
* we authenticate "on behalf of a user", to allow users to see their own calendar or another user's calendar into the web interface.
Typically, when the page is loaded, Chill first check that an authorization token exists. If not, the user is redirected to Microsoft Azure for authentification and a new token is grabbed (most of the times, this is transparent for users).
Typically, when the page is loaded, Chill first checks that an authorization token exists. If not, the user is redirected to Microsoft Azure for authentification, and a new token is grabbed (most of the times, this is transparent for users).
* Chill also acts "as a machine", to synchronize calendars with a daemon background.
One can access the configuration using this screen (it is quite well hidden into the multiple of tabs):
.. figure:: ./oauth_app_registration.png
You can find the oauth configuration on the "Securité > Autorisations" tab and click on "application registration" (not translated).
You can find the oauth configuration on the "Securité > Autorisations" tab, and click on "application registration" (not translated).
Add a redirection URI for your authentification:
Add a redirection URI for you authentification:
.. figure:: ./oauth_api_authentification.png
The URI must be "your chill public url" with :code:`/connect/azure/check` at the end.
The URI must be "your chill public url" with `/connect/azure/check` at the end.
Allow some authorizations for your app:
.. figure:: ./oauth_api_autorisees.png
Take care of the separation between autorization "on behalf of a user" (déléguée), or "for a machine" (application).
Take care of the separation between authorization "on behalf of a user" (déléguée), or "for a machine" (application).
Some explanation:
* Users must be allowed to read their user profile (:code:`User.Read`), and the profile of other users (:code:`User.ReadBasicAll`);
* They must be allowed to read their calendar (:code:`Calendars.Read`), and the calendars shared with them (:code:`Calendars.Read.Shared`);
* Users must be allowed to read their user profile (`User.Read`), and the profile of other users (`User.ReadBasicAll`);
* They must be allowed to read their calendar (`Calendars.Read`), and the calendars shared with them (`Calendars.Read.Shared`);
The sync daemon must have write access:
* the daemon must be allowed to read all users and their profile, to establish a link between them and the Chill's users: (:code:`Users.Read.All`);
* it must also be allowed to read and write into the calendars (:code:`Calendars.ReadWrite.All`);
* for sending invitation to other users, the permission (:code:`Mail.Send`) must be granted;
* and, for reading the absence status of the user and sync it with chill, it must be able to read the mailboxSettings (:code:`MailboxSettings.Read`).
* the daemon must be allowed to read all users and their profile, to establish a link between them and the Chill's users: (`Users.Read.All`);
* it must also be allowed to read and write into the calendars (`Calendars.ReadWrite.All`);
* for sending invitation to other users, the permission (`Mail.Send`) must be granted;
* and, for reading the absence status of the user and sync it with chill, it must be able to read the mailboxSettings (`MailboxSettings.Read`).
At this step, you might choose to accept those permissions for all users, or let them do it by yourself.
At this step, you might choose to accept those permissions for all users or let them do it by yourself.
Grab your client id:
.. figure:: ./oauth_api_client_id.png
This will be your :code:`OAUTH_AZURE_CLIENT_ID` variable.
This will be your `OAUTH_AZURE_CLIENT_ID` variable.
Generate a secret:
.. figure:: ./oauth_api_secret.png
This will be your `OAUTH_AZURE_CLIENT_SECRET` variable.
This will be your :code:`OAUTH_AZURE_CLIENT_SECRET` variable.
And get you azure's tenant id, which is the same as the :code:`SAML_IDP_APP_UUID` (see above).
And get you azure's tenant id, which is the same as the `SAML_IDP_APP_UUID` (see above).
Your variables will be:
.. code-block::
OAUTH_AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OAUTH_AZURE_CLIENT_TENANT=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OAUTH_AZURE_CLIENT_SECRET: 3-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Then, configure chill:
Enable the calendar sync with microsoft azure:
.. code-block:: yaml
Enable the calendar sync with Microsoft Azure:
```yaml
# config/packages/chill_calendar.yaml
chill_calendar:
remote_calendars_sync:
microsoft_graph:
enabled: true
```
and configure the oauth client:
.. code-block:: yaml
```yaml
# config/packages/knp_oauth2_client.yaml
knpu_oauth2_client:
clients:
@@ -296,35 +256,30 @@ and configure the oauth client:
tenant: '%env(OAUTH_AZURE_CLIENT_TENANT)%'
url_api: 'https://graph.microsoft.com/'
default_end_point_version: '2.0'
```
You can now process for the first api authorization on the application side, (unless you did it in the Azure interface) and get the first token by using :
You can now process for the first api authorization on the application side, (unless you did it in the Azure interface), and get a first token, by using :
`bin/console chill:calendar:msgraph-grant-admin-consent`
:code:`bin/console chill:calendar:msgraph-grant-admin-consent`
This will generate an url that you can use to grant your app for your tenant. The redirection may fail in the browser, but this is not relevant: if you get an authorization token in the CLI, the authentication works.
This will generate a url that you can use to grant your app for your tenant. The redirection may fails in the browser, but this is not relevant: if you get an authorization token in the CLI, the authentication works.
### Run the processes to synchronize
Run the processes to synchronize
--------------------------------
The calendar synchronization is processed using symfony messenger. It seems to be interesting to configure a queue (in the postgresql database it is the simplest way), and to run a worker for synchronization, at least in production.
The calendar synchronization is processed using symfony messenger. It seems to be intersting to configure a queue (in the postgresql database it is the most simple way), and to run a worker for synchronization, at least in production.
This cli command does the association between chill's users and Microsoft's users:
The association between chill's users and Microsoft's users is done by this cli command:
.. code-block::
bin/console chill:calendar:msgraph-user-map-subscribe
`bin/console chill:calendar:msgraph-user-map-subscribe`
This command:
* will associate the Microsoft's user metadata in our database;
* and, most important, create a subscription to get notification when the user alter his calendar, to sync chill's event and ranges in sync.
* and, most important, create a subscription to get notification when the user alters his calendar, to sync chill's event and ranges in sync.
The subscription least at most 3 days. This command should be runned:
The subscription is at least at most 3 days. This command should be run:
* at least each time a user is added;
* and, at least, every three days.
In production, we advise to run it at least every day to get the sync working.
In production, we advise running it at least every day to get the sync working.

21
docs/source/installation/prod-calendar-sms-sending.md Normal file
View File

@@ -0,0 +1,21 @@
## Send short messages (SMS) with the calendar bundle
To activate the sending of messages, you should run this command on a regular basis (using, for instance, a cronjob):
`bin/console chill:calendar:send-short-messages`
A transporter must be configured for the message to be effectively sent.
### Configure OVH Transporter
Currently, this is the only one transporter available.
To configure this, add this config variable in your environment:
```env
SHORT_MESSAGE_DSN=ovh://applicationKey:applicationSecret@endpoint?consumerKey=xxxx&sender=yyyy&service_name=zzzz
```
To generate the application key, secret, and consumerKey, refers to their `documentation ](https://docs.ovh.com/gb/en/api/first-steps-with-ovh-api/).
Before to be able to send your first sms, you must enable your account, grab some credits, and configure a sender. The service_name is an internal configuration generated by OVH.

27
docs/source/installation/prod-calendar-sms-sending.rst
View File

@@ -1,27 +0,0 @@
Send short messages (SMS) with calendar bundle
==============================================
To activate the sending of messages, you should run this command on a regularly basis (using, for instance, a cronjob):
.. code-block:: bash
bin/console chill:calendar:send-short-messages
A transporter must be configured for the message to be effectively sent.
Configure OVH Transporter
-------------------------
Currently, this is the only one transporter available.
For configuring this, simply add this config variable in your environment:
```env
SHORT_MESSAGE_DSN=ovh://applicationKey:applicationSecret@endpoint?consumerKey=xxxx&sender=yyyy&service_name=zzzz
```
In order to generate the application key, secret, and consumerKey, refers to their `documentation <https://docs.ovh.com/gb/en/api/first-steps-with-ovh-api/>`_.
Before to be able to send your first sms, you must enable your account, grab some credits, and configure a sender. The service_name is an internal configuration generated by OVH.

62
docs/source/installation/prod.md Normal file
View File

@@ -0,0 +1,62 @@
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 for production
An installation uses these services, which are deployed using docker containers:
* a php-fpm image, which runs the Php and Symfony code for Chill;
* a nginx image, which serves the assets and usually proxies the php requests to the fpm image;
* a redis server, which stores the cache, sessions (this is currently hardcoded in the php image), and some useful keys (like wopi locks);
* a postgresql database. The use of postgresql is mandatory;
* a relater service, which transforms odt templates to full documents (replacing the placeholders);
Some external services:
* (required) an openstack object store, configured with `temporary url <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html>` configured (no openstack users are required). This is currently the only way to store documents from chill;
* a mailer service (SMTP)
* (optional) a service for verifying phone number. Currently, only Twilio is possible;
* (optional) a service for sending Short Messages (SMS). Currently, only Ovh is possible;
The `docker-compose.yaml` file of chill app is a basis for a production install. The environment variable in the ```.env``` and ```.env.prod``` should be overridden by environment variables, or ```.env.local``` files.
This should be adapted to your needs:
* The images for php and nginx apps are pre-compiled images, with the default configuration and bundle. If they do not fullfill your needs, you should compile your own images.
.. TODO:
As the time of writing (2022-07-03) those images are not published yet.
* Think about how you will back up your database. Some adminsys find it easier to store a database outside of docker, which might be easier to administrate or replicate.
## Run migrations on each update
Every time you start a new version, you should apply update the sql schema:
- running ``bin/console doctrine:migration:migrate`` to run SQL migration;
- synchronizing SQL views to the last state: ``bin/console chill:db:sync-views``
## Cron jobs
The command `chill:cron-job:execute` should be executed every 15 minutes (more or less).
This command should never be executed concurrently. It should be not having more than one process for a single instance.
## Post-install tasks
- import addresses. See [addresses](addresses.md).
## Tweak symfony messenger
Calendar sync is processed using symfony messenger.
You can tweak the configuration
Going further:
* Configure the saml login and synchronization with Outlook api

71
docs/source/installation/prod.rst
View File

@@ -1,71 +0,0 @@
.. 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".
.. _prod:
Installation for production
###########################
An installation use these services, which are deployed using docker containers:
* a php-fpm image, which run the Php and Symfony code for Chill;
* a nginx image, which serves the assets, and usually proxy the php requests to the fpm image;
* a redis server, which stores the cache, sessions (this is currently hardcoded in the php image), and some useful keys (like wopi locks);
* a postgresql database. The use of postgresql is mandatory;
* a relatorio service, which transform odt templates to full documents (replacing the placeholders);
Some external services:
* (required) an openstack object store, configured with `temporary url <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html>` configured (no openstack users is required). This is currently the only way to store documents from chill;
* a mailer service (SMTP)
* (optional) a service for verifying phone number. Currently, only Twilio is possible;
* (optional) a service for sending Short Messages (SMS). Currently, only Ovh is possible;
The `docker-compose.yaml` file of chill app is a basis for a production install. The environment variable in the ```.env``` and ```.env.prod``` should be overriden by environment variables, or ```.env.local``` files.
This should be adapted to your needs:
* The image for php and nginx apps are pre-compiled images, with the default configuration and bundle. If they do not fullfill your needs, you should compile your own images.
.. TODO:
As the time of writing (2022-07-03) those images are not published yet.
* Think about how you will backup your database. Some adminsys find easier to store database outside of docker, which might be easier to administrate or replicate.
Run migrations on each update
=============================
Every time you start a new version, you should apply update the sql schema:
- running ``bin/console doctrine:migration:migrate`` to run sql migration;
- synchonizing sql views to the last state: ``bin/console chill:db:sync-views``
Cron jobs
=========
The command :code:`chill:cron-job:execute` should be executed every 15 minutes (more or less).
This command should never be executed concurrently. It should be not have more than one process for a single instance.
Post-install tasks
==================
- import addresses. See :ref:`addresses`.
Tweak symfony messenger
=======================
Calendar sync is processed using symfony messenger.
You can tweak the configuration
Going further:
* Configure the saml login and synchronisation with Outlook api