server configuration environment files

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.

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 and [models/server_env_tech_name_mixin.py] (models/server_env_tech_name_mixin.py)

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.

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.addons.server_environment import uninstall

def uninstall_hook(env): 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(env): 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:

• 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).
• 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).
• 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 }, )
• 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.