Metadata-Version: 2.1
Name: odoo-addon-server_environment
Version: 16.0.1.1.4
Summary: move some configurations out of the database
Home-page: https://github.com/OCA/server-env
Author: Camptocamp,Odoo Community Association (OCA)
Author-email: support@odoo-community.org
License: LGPL-3
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 16.0
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Requires-Dist: odoo<16.1dev,>=16.0a

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

======================================
server configuration environment files
======================================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:04a086fff701c37b7e977c7ab955d3715e574576f6d7b306288b0459c0feced7
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Production%2FStable-green.png
    :target: https://odoo-community.org/page/development-status
    :alt: Production/Stable
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
    :alt: License: LGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--env-lightgray.png?logo=github
    :target: https://github.com/OCA/server-env/tree/16.0/server_environment
    :alt: OCA/server-env
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/server-env-16-0/server-env-16-0-server_environment
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/server-env&target_branch=16.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

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*').

**Table of contents**

.. contents::
   :local:

Installation
============

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``.

Configuration
=============

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

Or set the `RUNNING_ENV` or `ODOO_STAGE` environment variable. If both all are set config file
will take the precedence on environment and `RUNNING_ENV` over `ODOO_STAGE`.

`ODOO_STAGE` is used for odoo.sh platform where we can't set `RUNNING_ENV`, possible
observed values are `production`, `staging` and `dev`

Values associated to keys containing 'passw' are only displayed in the 'dev'
environment.

If you don't provide any value, `test` is used as a safe default.

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
    "

**WARNING**

  `my_sftp` must match the name of the record.
  If you want something more reliable use `server.env.techname.mixin`
  and use `tech_name` field to reference records.
  See "USAGE".


Default values
~~~~~~~~~~~~~~

When using the ``server.env.mixin`` mixin, for each env-computed field, a
companion field ``<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


Server environment integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Read the documentation of the class `models/server_env_mixin.py
<models/server_env_mixin.py>`_ and `models/server_env_tech_name_mixin.py
<models/server_env_tech_name_mixin.py>`_

Usage
=====

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
<models/server_env_mixin.py>`__.


If you want to have a technical name to reference::

    class StorageBackend(models.Model):
        _name = "storage.backend"
        _inherit = ["storage.backend", "server.env.techname.mixin"]

        [...]

Restoring columns on uninstall
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When ``server.env.mixin`` is bound to an existing model, the ORM drops the
original stored columns for all env-managed fields. If the binding addon is
later uninstalled, those columns must be recreated so the database remains
usable.

Add an ``uninstall_hook`` to your addon and delegate to
``restore_env_managed_columns``::

    # your_addon/__init__.py
    from .hooks import uninstall_hook
    # your_addon/hooks.py
    from odoo import SUPERUSER_ID, api
    from odoo.addons.server_environment import uninstall

    def uninstall_hook(cr, registry):
        env = api.Environment(cr, SUPERUSER_ID, {})
        uninstall.restore_env_managed_columns(
            env,
            "storage.backend",
            ["directory_path", "other_field"],
        )

    # your_addon/__manifest__.py
    {
        ...
        "uninstall_hook": "uninstall_hook",
    }

The helper creates any missing columns (idempotent: safe to call multiple
times) and repopulates them with each record's current effective value —
whether that value came from an environment configuration file or from the
stored default field (``x_<field>_env_default``).

The hook must run *before* the ORM extensions are removed, which is guaranteed
by Odoo's uninstall sequence (hooks execute before
``Module.module_uninstall()``).

Handling required fields
^^^^^^^^^^^^^^^^^^^^^^^^

If a restored column is **required** (has a ``NOT NULL`` constraint) but has no
effective value (missing from environment config and no default field set), the
restoration will fail with a ``UserError``.

**Solution:** pass a ``field_defaults`` dictionary with fallback values::

    def uninstall_hook(cr, registry):
        env = api.Environment(cr, SUPERUSER_ID, {})
        restore_env_managed_columns(
            env,
            "ir.mail_server",
            ["smtp_host", "smtp_authentication"],
            field_defaults={
                "smtp_authentication": "login",  # fallback for required field
            },
        )

The helper will use the fallback value if provided and the computed field value
is empty. If no fallback is provided but a required field has no value, a
``UserError`` is raised with instructions on how to provide a ``field_defaults``
parameter.

Migrating when dropping server_environment dependency
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When refactoring an existing addon that embeds a ``server.env.mixin`` binding, you
may want to extract the binding into a separate *glue* addon and drop the
``server_environment`` dependency from the original. This keeps the base addon
lightweight while preserving server-environment features for those who install
the glue addon.

**Pattern:**

- **Original addon (v1)**: depends on ``server_environment`` and binds the mixin
  directly in model code.
- **Refactored addon (v2)**: removes ``server_environment`` from dependencies,
  removes the mixin binding and the related ORM model inheritance.
- **New glue addon** (optional, same version): depends on both
  ``server_environment`` and the original addon v2; re-adds the mixin binding in
  a separate module file.

**Migration checklist:**

1. In the **original addon's v2** ``__manifest__.py``:

   - Remove ``"server_environment"`` from ``depends``.
   - Remove the model file(s) that contained the mixin binding.
   - Update ``depends`` to add the new glue addon *if* the base addon still needs
     it (otherwise, make the glue addon optional for users who want env-binding).

2. In the **original addon's v2 model code**:

   - Delete or simplify the model class that inherited from
     ``server.env.mixin``.
   - If the model was only there for the binding, remove it entirely.
   - Restore the original field definitions (not as computed fields).

3. **Create a migration script** (if needed) to restore columns *during the addon
   upgrade*, before the ORM model extensions are unloaded. Use a ``@post_load``
   hook or a dedicated migration script::

       # migrations/18.0.1.0.0/post-restore-columns.py
       def migrate(cr, version):
           # Call the restoration logic while the v1 model is still active
           env = odoo.api.Environment(cr, odoo.SUPERUSER_ID, {})
           # If any field is required and may have no value in the environment,
           # provide a fallback via field_defaults
           restore_env_managed_columns(
               env,
               "storage.backend",
               ["directory_path", "other_field"],
               field_defaults={
                   "directory_path": "/tmp",  # fallback for required field
               },
           )

4. **Create the glue addon** with the model re-inheritance::

       # your_addon_env/__init__.py
       from . import models

       # your_addon_env/models/__init__.py
       from . import storage_backend

       # your_addon_env/models/storage_backend.py
       class StorageBackend(models.Model):
           _name = "storage.backend"
           _inherit = ["storage.backend", "server.env.mixin"]

           @property
           def _server_env_fields(self):
               return {"directory_path": {}}

       # your_addon_env/__manifest__.py
       {
           "name": "Storage Backend – Server Environment",
           "version": "18.0.1.0.0",
           "depends": ["server_environment", "storage_backend"],
           "installable": True,
       }

**Key points:**

- Column restoration must happen *during the addon upgrade* (step 3), not as an
  uninstall hook, because the original model binding is still active.
- The ``restore_env_managed_columns`` helper is idempotent and safe to call even
  if columns already exist.
- Users who do not need server environment features simply do *not* install the
  glue addon—the base addon continues to work with plain database columns.
- Users who do need server environment can install both the base addon (v2+) and
  the glue addon (same version) to get the binding back.

Known issues / Roadmap
======================

* 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.
* `server.env.techname.mixin`'s `tech_name` field could leverage the new option
  for computable / writable fields and get rid of some onchange / read / write code.

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-env/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/server-env/issues/new?body=module:%20server_environment%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
~~~~~~~

* Camptocamp

Contributors
~~~~~~~~~~~~

* Florent Xicluna (Wingo) <florent.xicluna@gmail.com>
* Nicolas Bessi <nicolas.bessi@camptocamp.com>
* Alexandre Fayolle <alexandre.fayolle@camptocamp.com>
* Daniel Reis <dgreis@sapo.pt>
* Holger Brunn <hbrunn@therp.nl>
* Leonardo Pistone <leonardo.pistone@camptocamp.com>
* Adrien Peiffer <adrien.peiffer@acsone.com>
* Thierry Ducrest <thierry.ducrest@camptocamp.com>
* Guewen Baconnier <guewen.baconnier@camptocamp.com>
* Thomas Binfeld <thomas.binsfeld@acsone.eu>
* Stéphane Bidoul <stefane.bidoul@acsone.com>
* Simone Orsi <simahawk@gmail.com>

Maintainers
~~~~~~~~~~~

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

This module is part of the `OCA/server-env <https://github.com/OCA/server-env/tree/16.0/server_environment>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
