From 6c97654e5e7a62a49ce5a6b9c7da9d86e09231ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 9 Jan 2025 16:05:58 +0100 Subject: [PATCH] Add documentation for document storage configuration Introduce a new guide detailing document storage options, including on-disk storage and cloud-based OpenStack integration. This document explains configuration steps, benefits, and limitations for both methods, and is now linked in the production installation index. --- docs/source/installation/document-storage.rst | 84 +++++++++++++++++++ .../installation/installation-production.rst | 1 + 2 files changed, 85 insertions(+) create mode 100644 docs/source/installation/document-storage.rst diff --git a/docs/source/installation/document-storage.rst b/docs/source/installation/document-storage.rst new file mode 100644 index 000000000..0b87d9eb2 --- /dev/null +++ b/docs/source/installation/document-storage.rst @@ -0,0 +1,84 @@ +Document storage +################ + +You can store document on two different ways: + +- on disk +- in the cloud, using object storage: currently only `openstack swift `_ 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 `_; +- `Temporary URL Middelware `_. + +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 `_ 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 + + diff --git a/docs/source/installation/installation-production.rst b/docs/source/installation/installation-production.rst index c02390b5a..30e8c91ce 100644 --- a/docs/source/installation/installation-production.rst +++ b/docs/source/installation/installation-production.rst @@ -323,6 +323,7 @@ Going further :maxdepth: 2 prod.rst + document-storage.rst load-addresses.rst prod-calendar-sms-sending.rst msgraph-configure.rst