From 55e5ff330fd0751c056bbdab716502d8eb9b6fe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Bidoul=20=28ACSONE=29?= Date: Tue, 6 Nov 2018 10:19:17 +0100 Subject: [PATCH] [IMP] server_environment: readme fragments --- server_environment/readme/CONFIGURE.rst | 89 +++++++++++++++++++ server_environment/readme/CONTRIBUTORS.rst | 10 +++ server_environment/readme/DESCRIPTION.rst | 14 +++ server_environment/readme/INSTALL.rst | 9 ++ server_environment/readme/ROADMAP.rst | 3 + server_environment/readme/USAGE.rst | 15 ++++ .../readme/CONTRIBUTORS.rst | 9 ++ .../readme/DESCRIPTION.rst | 3 + .../readme/INSTALL.rst | 5 ++ 9 files changed, 157 insertions(+) create mode 100644 server_environment/readme/CONFIGURE.rst create mode 100644 server_environment/readme/CONTRIBUTORS.rst create mode 100644 server_environment/readme/DESCRIPTION.rst create mode 100644 server_environment/readme/INSTALL.rst create mode 100644 server_environment/readme/ROADMAP.rst create mode 100644 server_environment/readme/USAGE.rst create mode 100644 server_environment_files_sample/readme/CONTRIBUTORS.rst create mode 100644 server_environment_files_sample/readme/DESCRIPTION.rst create mode 100644 server_environment_files_sample/readme/INSTALL.rst diff --git a/server_environment/readme/CONFIGURE.rst b/server_environment/readme/CONFIGURE.rst new file mode 100644 index 0000000..deca37c --- /dev/null +++ b/server_environment/readme/CONFIGURE.rst @@ -0,0 +1,89 @@ +To configure this module, you need to edit the main configuration file +of your instance, and add a directive called ``running_env``. Commonly +used values are 'dev', 'test', 'production':: + + [options] + running_env=dev + +Values associated to keys containing 'passw' are only displayed in the 'dev' +environment. + +You have several possibilities to set configuration values: + +server_environment_files +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can edit the settings you need in the ``server_environment_files`` addon. The +``server_environment_files_sample`` can be used as an example: + +* values common to all / most environments can be stored in the + ``default/`` directory using the .ini file syntax; +* each environment you need to define is stored in its own directory + and can override or extend default values; +* you can override or extend values in the main configuration + file of your instance; + +Environment variable +~~~~~~~~~~~~~~~~~~~~ + +You can define configuration in the environment variable ``SERVER_ENV_CONFIG`` +and/or ``SERVER_ENV_CONFIG_SECRET``. The 2 variables are handled the exact same +way, this is only a convenience for the deployment where you can isolate the +secrets in a different, encrypted, file. They are multi-line environment variables +in the same configparser format than the files. +If you used options in ``server_environment_files``, the options set in the +environment variable override them. + +The options in the environment variable are not dependent of ``running_env``, +the content of the variable must be set accordingly to the running environment. + +Example of setup: + +A public file, containing that will contain public variables:: + + # These variables are not odoo standard variables, + # they are there to represent what your file could look like + export WORKERS='8' + export MAX_CRON_THREADS='1' + export LOG_LEVEL=info + export LOG_HANDLER=":INFO" + export DB_MAXCONN=5 + + # server environment options + export SERVER_ENV_CONFIG=" + [storage_backend.my-sftp] + sftp_server=10.10.10.10 + sftp_login=foo + sftp_port=22200 + directory_path=Odoo + " + +A second file which is encrypted and contains secrets:: + + # This variable is not an odoo standard variable, + # it is there to represent what your file could look like + export DB_PASSWORD='xxxxxxxxx' + # server environment options + export SERVER_ENV_CONFIG_SECRET=" + [storage_backend.my-sftp] + sftp_password=xxxxxxxxx + " + +Default values +~~~~~~~~~~~~~~ + +When using the ``server.env.mixin`` mixin, for each env-computed field, a +companion field ``_env_default`` is created. This field is not +environment-dependent. It's a fallback value used when no key is set in +configuration files / environment variable. + +When the default field is used, the field is made editable on Odoo. + +Note: empty environment keys always take precedence over default fields + + +Keychain integration +~~~~~~~~~~~~~~~~~~~~ + +Read the documentation of the class `models/server_env_mixin.py +`_. diff --git a/server_environment/readme/CONTRIBUTORS.rst b/server_environment/readme/CONTRIBUTORS.rst new file mode 100644 index 0000000..640f3a8 --- /dev/null +++ b/server_environment/readme/CONTRIBUTORS.rst @@ -0,0 +1,10 @@ +* Alexandre Fayolle +* Daniel Reis +* Florent Xicluna +* Guewen Baconnier +* Holger Brunn +* Joël Grand-Guillaume +* Nicolas Bessi +* Wingo +* Yannick Vaucher +* Stéphane Bidoul diff --git a/server_environment/readme/DESCRIPTION.rst b/server_environment/readme/DESCRIPTION.rst new file mode 100644 index 0000000..8fc7356 --- /dev/null +++ b/server_environment/readme/DESCRIPTION.rst @@ -0,0 +1,14 @@ +This module provides a way to define an environment in the main Odoo +configuration file and to read some configurations from files +depending on the configured environment: you define the environment in +the main configuration file, and the values for the various possible +environments are stored in the ``server_environment_files`` companion +module. + +The ``server_environment_files`` module is optional, the values can be set using +an environment variable with a fallback on default values in the database. + +The configuration read from the files are visible under the Configuration +menu. If you are not in the 'dev' environment you will not be able to +see the values contained in the defined secret keys +(by default : '*passw*', '*key*', '*secret*' and '*token*'). diff --git a/server_environment/readme/INSTALL.rst b/server_environment/readme/INSTALL.rst new file mode 100644 index 0000000..8ad360c --- /dev/null +++ b/server_environment/readme/INSTALL.rst @@ -0,0 +1,9 @@ +By itself, this module does little. See for instance the +``mail_environment`` addon which depends on this one to allow configuring +the incoming and outgoing mail servers depending on the environment. + +You can store your configuration values in a companion module called +``server_environment_files``. You can copy and customize the provided +``server_environment_files_sample`` module for this purpose. Alternatively, you +can provide them in environment variables ``SERVER_ENV_CONFIG`` and +``SERVER_ENV_CONFIG_SECRET``. diff --git a/server_environment/readme/ROADMAP.rst b/server_environment/readme/ROADMAP.rst new file mode 100644 index 0000000..4c8096a --- /dev/null +++ b/server_environment/readme/ROADMAP.rst @@ -0,0 +1,3 @@ +* it is not possible to set the environment from the command line. A + configuration file must be used. +* the module does not allow to set low level attributes such as database server, etc. diff --git a/server_environment/readme/USAGE.rst b/server_environment/readme/USAGE.rst new file mode 100644 index 0000000..6c8f221 --- /dev/null +++ b/server_environment/readme/USAGE.rst @@ -0,0 +1,15 @@ +You can include a mixin in your model and configure the env-computed fields +by an override of ``_server_env_fields``. + +:: + + class StorageBackend(models.Model): + _name = "storage.backend" + _inherit = ["storage.backend", "server.env.mixin"] + + @property + def _server_env_fields(self): + return {"directory_path": {}} + +Read the documentation of the class and methods in `models/server_env_mixin.py +`__. diff --git a/server_environment_files_sample/readme/CONTRIBUTORS.rst b/server_environment_files_sample/readme/CONTRIBUTORS.rst new file mode 100644 index 0000000..af224ea --- /dev/null +++ b/server_environment_files_sample/readme/CONTRIBUTORS.rst @@ -0,0 +1,9 @@ +* Alexandre Fayolle +* Daniel Reis +* Florent Xicluna +* Guewen Baconnier +* Holger Brunn +* Joël Grand-Guillaume +* Nicolas Bessi +* Wingo +* Yannick Vaucher diff --git a/server_environment_files_sample/readme/DESCRIPTION.rst b/server_environment_files_sample/readme/DESCRIPTION.rst new file mode 100644 index 0000000..6e0ccef --- /dev/null +++ b/server_environment_files_sample/readme/DESCRIPTION.rst @@ -0,0 +1,3 @@ +This is an example module to be used for +`server_environment_files`. Check that module's README for more +information. diff --git a/server_environment_files_sample/readme/INSTALL.rst b/server_environment_files_sample/readme/INSTALL.rst new file mode 100644 index 0000000..04ed532 --- /dev/null +++ b/server_environment_files_sample/readme/INSTALL.rst @@ -0,0 +1,5 @@ +Do not install this module as is. Copy it to a directory in your +addons-path and rename it to +`server_environment_files`, then edit the various configurations. + +This module is not testable on runbot (see above).