Configuring an instance
A save applies itself
Every instance has the configuration you have saved and the configuration its container was actually built with. Antelao stores a snapshot of the second one.
Saving queues the apply behind the save. There is no second button: the apply converges the running
instance - the odoo.conf, the nginx site, a restart when the change needs one - and you watch it
on the Jobs page like any other job.
Changing the edition is applied in full. Switching to Enterprise fetches the Enterprise add-ons
at the recorded commit (the newest one when none is recorded), writes odoo.conf and recreates the
container; it needs no image rebuild. The fetch uses the GitHub token on the instance's git
configuration, and when it fails the apply fails with the reason and the instance keeps running as
it was.
Switching an Enterprise instance to Community removes its Enterprise add-ons when the change is applied. A database with Enterprise modules installed loses those modules' code. Take a backup of the instance first, and uninstall the Enterprise modules in Odoo before you switch if the instance is to stay on Community. Switching back to Enterprise fetches the add-ons again.
Changing the version is not an upgrade. See Changing the Odoo version.
An apply also checks the files themselves, not only the snapshot, and the one a save queues is
careful with what it finds. An odoo.conf that no longer matches the saved configuration is left as
it is by that apply, unless the change it applies rewrites the file anyway, because putting it right
restarts the instance. The job says so, with the command that puts it right. An apply you ask for -
Apply or Retry the apply on the Pending changes page, or ohm instance drift --apply -
rewrites the file and restarts the instance, so it is the way to put a drifted instance right when a
restart suits. An Enterprise instance whose add-ons are missing or not at the recorded commit is put
right by every apply.
Pending changes
What still differs after the apply is on the Pending changes page, each entry with its reason and the action that goes with it:
- an apply on its way,
- a failed apply, with its error and a retry,
- or something the apply deliberately leaves to you: the image rebuild, the certificate, the modules, the server install.
The badge beside your account counts them.
pelmo$ ohm instance drift --instance fanespelmo$ ohm instance drift --instance fanes --apply--apply retries the apply and follows it. --apply --force applies the instance in full,
rewriting its configuration file and restarting it, even when nothing drifts.
On the server itself, as root and without a saved connection, add --local. The command then asks
the server's own management API, exactly as over a connection, so the API has to be running; the
apply is the same job the console queues:
sudo ohm instance drift --instance fanes --local
sudo ohm instance drift --instance fanes --apply --force --local
Some settings only take effect when the container is recreated, not restarted. Anything that
changes a bind mount is in that category, addons paths in particular. The apply picks the right
action for you; doing it by hand with instance container restart may silently do nothing.
Editing
Instance configuration is edited in the console: the instance's Configuration page. The CLI
reads instances and acts on them; the ohm instance config commands work on the stored
configuration as a whole, on the server or remotely:
| Command | What it does |
|---|---|
ohm instance config preset | Applies an environment preset to the instance's stored configuration |
ohm instance config rebuild | Writes the instance's Odoo configuration file again from its stored configuration |
ohm instance config validate-dns | Checks that the instance's host names resolve to this server |
ohm instance config import | Builds a new instance from an exported configuration file, like Import configuration |
ohm instance config export | Exports every instance's configuration as a file into the directory -e, --export-path names, on the machine you run it on |
pelmo$ ohm instance config validate-dns --instance fanesBoth work on the machine you run them on, wherever the server is: ohm instance config export
downloads each instance's configuration, as the export button on the instance list does, and writes
the files into --export-path there; ohm instance config import reads its -j, --json file there
and sends it to the server, as Import configuration does. --skip-existing-files keeps a file
that is already in the directory.
pelmo$ ohm instance config export --export-path ./configurationsThe pages an instance carries:
| Tab | What it decides | Covered in |
|---|---|---|
| Configuration | Host names, version, edition, role, classification, description, the Docker image, and the workload and tuning sized from it | this page and Tuning |
| Modules | Custom addon repositories and their credentials, the commit each is pinned to and the head of its branch, and the modules | Git addons |
| Databases | The instance's databases and which one it serves | Managing databases |
| Health | The daily health report and the auto repair | Instance health |
| Certificate | The instance's TLS certificate | Certificates |
| Backup | Backup mode, storage providers, schedule and the archives that exist | Targets |
| Restore | Restore mode, restore sources and schedule | Restoring |
| Upgrade | The move of the instance's databases to a newer Odoo major version | Upgrading to a newer Odoo version |
| Firewall | Which addresses may reach which of the instance's paths | An instance's own firewall |
| Code | The instance's code in the browser, read-only or in the editor | The code editor |
The history button beside Save on the Configuration tab opens Configuration History: every saved version of the instance's configuration, what changed, and a way to restore an earlier one.
Duplicate this instance, among the instance's buttons, opens the New instance wizard on Clone an existing instance. See Duplicate and import.
Allow editing in the browser editor
The Configuration tab carries Allow editing in the browser editor: whether the instance's Code tab opens the editor writable here. It is on by default for a development instance and off for every other, and changing the Role above moves the default with it. Off, the Code tab shows the instance's code read-only.
Switching it on for an instance whose Role is not Development shows a warning: Code can be edited on a live instance. An administrator with a developer workspace profile then opens the Code tab writable, with a terminal and git, so whoever edits a file edits what the instance's users run, and the next module update or automatic git update can overwrite it. Only an Administrator can change the switch, and it is saved with the form.
The Docker image
The Docker image card on the Configuration page changes what the instance's image is built from, the same choices as the creation wizard: the Image source (Pre-built from Docker Hub, or Built on this server from Odoo's recipe) and the Odoo inside it. A pre-built image has an Image version - Latest, or one of the dated images Docker Hub publishes for the version - and an Odoo build: The image's own build, or a nightly build that is installed into the Docker Hub image during the build, checked against Odoo's own checksum, which makes each build several minutes longer and the image larger. A built image has its Odoo build alone. Build & activate rebuilds the image and recreates the container on it. A build reuses what Docker already has and redoes only what changed; Rebuild from scratch builds every layer again and pulls the base image afresh, which is the slow way and the one for an image that has to be known clean.
APT packages and Python packages add packages to the image, for example a font or a library
a custom module needs. Enter one package per line: an APT package as APT names it, such as
fonts-noto-cjk, and a Python package with or without a version, such as openpyxl or
pandas==2.2.3. Commas do not separate entries, because they belong to version ranges such as
pandas>=2,<3. Each list takes up to 100 packages.
Each entry is checked before anything is queued: it has to be a package name, optionally with a version, so options, addresses and paths are refused. Build & activate rebuilds the image with the lists, and they are saved on the instance once the build has succeeded. A build that fails changes nothing: the instance keeps running on its current image, and the lists stay as they were. Removing a line and building again takes that package out of the image. A backup carries both lists, so a restored instance builds with them.
Extra packages are installed into the image as they are. A wrong name stops the build, and a package that conflicts with Odoo can stop the instance from starting. Try them on a copy of the instance first.
The job's log lists every build step as it starts, with what it does and the time the step before it took; a step of Odoo's own recipe shows its raw instruction. While a step runs, the log shows how far it got: downloads, packages and every warning or error. A step that runs past a minute adds a line every 30 seconds, and the build closes with a summary: how long it took, its three slowest steps and the image's size.
When the Image version the instance is pinned to is one Docker Hub does not publish, the card says which build the next build moves it to, or that the next build is refused because Docker Hub has no later one. See Where the image comes from.
Odoo build in image is the build the running image carries and how far it is behind the newest
one its source offers, as the server last checked it: right after the instance is installed or its
image activated, a few minutes after every start of the management API, and with the daily update
check. With a build installed into a pre-built image it also says how far the Docker Hub image
underneath is behind the newest one. A pre-built image on a version tag such as 19.0 names its
build nowhere in its tag, so the server records the build Docker Hub's image carries when it builds
the instance's image, and reads it from Docker Hub for an image built before that. Odoo publishes a build almost every day, so being behind is
normal; the Overview's badge and the Updates page only flag an instance
past the server's Odoo build age warning, for a newer build or a newer Docker Hub image, and say
which.
The same two warnings as in the wizard show on this card and on the instance's Overview when Odoo no longer supports the version or no longer maintains its Docker image.
pelmo$ ohm instance image build --instance fanes --image-source Built --odoo-release 20260925pelmo$ ohm instance image build --instance fanes --image-source Prebuilt --odoo-release default --prebuilt-odoo-release 20260925--image-source is Prebuilt or Built; --odoo-release is a build date or default: the image
version on a pre-built image (Latest by default), the build Odoo's recipe installs on a built one
(Newest by default). --prebuilt-odoo-release is the build installed into a pre-built image, or
default for the image's own build. All are kept for every later rebuild.
pelmo$ ohm instance image build --instance fanes --apt fonts-noto-cjk --pip openpyxl --pip pandas==2.2.3--apt and --pip take one package each and are repeated for several. The list you give replaces
the instance's, and the option with no value clears it; left out, the list stays as it is.
Changing the Odoo version
The Version on the Configuration tab is the Odoo version the instance's image is built for. Saving a new one puts an image rebuild on Pending changes; the rebuild and the restart then run the new version of Odoo against the databases the instance already has. Saving a version migrates nothing: moving a database to a newer major version is the job of the Upgrade tab.
Choosing another major version on an instance that holds databases shows a warning under the field, for example:
The databases of this instance are on 17.0 and will not work on 18.0; use Upgrade to move them.
It is a warning and not a refusal, so the save still goes through.
Odoo does not open a database made by an older major version as if nothing changed: its data has to be migrated first. Changing the version of an instance that holds databases leaves it running a version of Odoo its databases were not made for. Change the version only on an instance with no databases yet, or to undo a version chosen by mistake before any data went in. To move a database to a newer major version, see Upgrading an instance to a newer Odoo version.
Where instance configuration is stored
In the master database, with everything else the product knows. There is no per-instance configuration file to edit, and no server setting that moves it.
Moving a configuration between instances
The instance list has an export button per row and an Import configuration panel: the export gives you the instance's configuration as JSON, and the import builds an instance from one.
That is useful for review, for version control, and for standing up a similar instance elsewhere.
An exported configuration carries the instance's stored credentials as encrypted values only this server can read back, and never the instance's Odoo master password (the one Odoo's database manager asks for): an imported instance always gets a master password of its own. The files the command line writes can be read by your own account only. Treat them as secrets all the same.
Configuration files and backups written by earlier releases still contain the instance's master password in plain text. Delete them, or keep them as carefully as a password.
An exported configuration carries the source instance's active database name. Import it onto another instance and that instance now believes it owns the source's database. Removing it then attempts to drop the source's live database.
An ownership check is the only thing that stops this. Treat configuration import as a tool for building a new instance, never for editing an existing one.
Presets
Presets carry a set of defaults for a kind of instance, so that "a production instance" and "a
throwaway test instance" do not have to be configured field by field. A preset is chosen when an
instance is restored, cloned or imported, and ohm instance config preset applies one to an
existing instance.
The presets differ in more than defaults. Production keeps an instance's identity when it is restored or imported; every other preset issues new identifiers, which is what stops a staging copy believing it is the original. See Duplicate and import.
Test and Staging, and automatic git updates
The Test and Staging presets switch on automatic git updates: the instance's custom modules move to their branch heads and the instance restarts on its own. Because that changes a running instance without anyone pressing a button, it is never switched on without being asked for:
- Applying the preset to an installed instance whose automatic git updates are off asks first.
On the command line,
ohm instance config presetasks at the terminal;--yesanswers yes, and--no-git-auto-updateapplies the preset with the updates left off. Without a terminal and without either, nothing is changed and the command says how to answer. - Restoring, cloning and importing an instance with Test or Staging starts it with automatic git
updates off, unless you switch Automatic git updates on in the New instance wizard or on
Import configuration, or pass
--git-auto-updatetoohm instance importorohm instance config import.
pelmo$ ohm instance config preset --instance fanes --preset staging --no-git-auto-updateApplied with the updates on, they run from the next poll. The preset's other changes reach the
running instance with the next apply, ohm instance drift --instance fanes --apply.
The Role and the environment banner
The Role on the Configuration page is also what the instance's Odoo pages show. Every database of the instance carries an environment banner and ribbon, and a save that changes the Role rewrites them in every database, before the apply:
| Role | Banner and ribbon |
|---|---|
| Development | DEVELOPMENT |
| Staging | STAGING |
| Production | None |
| Undefined | Left as they are |
Nothing else in the databases changes with the Role: mail servers, scheduled actions and integrations stay as they are, so moving a staging copy to Production never switches its outgoing mail or scheduled actions back on. A save that keeps the Role does not touch the databases.
A database that cannot be rewritten fails the job with its name, and the others are still done.
Checking the DNS records
Host names are what nginx serves the instance on and what a certificate is requested for. A host name another instance on the server already answers, one another site uses, or the server's or the management console's own name is refused when you save, and an instance whose site would clash with another is not applied until one of them drops the name. Check them before you rely on either:
pelmo$ ohm server config validate-dns