Skip to main content

Updating Antelao

Checking​

Remote or local
$ ohm server update

server update is read-only. It reports newer container images and newer apt packages and changes nothing. The console shows the same on its Updates page.

Odoo builds behind the newest​

The same check measures every instance's Odoo build against the newest one its image source offers: the nightly builds for an image built on the server, Docker Hub's dated images for a pre-built one running the image's own build. A pre-built image with a build installed into it is measured both ways: its build against the nightly builds and the Docker Hub image underneath against Docker Hub's, and either one being too far behind flags it. Odoo publishes a build almost every day, so the Updates page lists only the instances further behind than the Odoo build age warning (days) under Configuration allows - 30 by default, 0 to never flag one - and says whether the build or the image is behind. An instance is rebuilt from its own Docker image card, not from this page.

Applying​

Remote or local
$ ohm server upgrade

Both commands go through the management API over a connection, and the agent performs the work: an upgrade recreates ohm-api and ohm-web, and a process cannot reliably replace the container it is itself running in.

Add --local and they run in your own process against the host's Docker daemon instead. That form must be run on the host, and never from inside a container, for the same reason.

An upgrade that finds a newer agent image checks its signature and writes /var/lib/ohm-agent/upgrade-requested. On the host, the installed ohm checks that image's signature again and only then restarts the agent on it, within seconds; until it has, the API sends no work to the old agent.

The agent that comes up on the new image then finishes the same upgrade: it checks the server against the new release's own versions and moves GeoIP, Fail2Ban and every other service the release pins in that same task, so one upgrade brings the whole server onto the release. The Updates page follows that one task across the agent's restart, and the task ends only when this second part does. If the host started the old agent again instead, the task fails and says why.

Docker Engine and the antelao-ohm package itself are yours to update with apt.

A release that changes the master database​

The Updates page and ohm server upgrade cannot move a server across a change to the master database's schema: they refuse before anything is recreated, and say so. Such a release is applied on the server, with the package and a repair:

Remote or local
$ sudo apt-get update
sudo apt-get install --only-upgrade antelao-ohm
sudo ohm install

0.18.0 is such a release, so every server moves to it this way. An update like this cannot be taken back with Roll back.

Releases and image signatures​

A server runs the release it was installed or last updated to. The management API, the console and the host agent all run that release's images, and nothing moves them but ohm install or an update you apply: a restart or a reboot never brings in newer images on its own. The Updates page offers the next release when one is published, and applying it moves the whole server to it. An update never moves a server to an older release than the one it runs: only Roll back does, when you ask for it. The release is not a setting you edit, so moving it is never listed on Pending changes.

Every Antelao image a server runs is signed when it is released, and the server checks the signature before it creates or recreates a container from it - the management API and console, the host agent, the GeoIP and Fail2Ban services, the CrowdSec bouncer, the SSH gateway and the browser editor. The keys it checks against come with the antelao-ohm package; their public halves are in /usr/share/antelao-ohm/ if you want to check an image yourself with cosign.

  • An image whose signature does not hold is refused. The container keeps the image it runs, the server's audit log records the refusal, and the Image signature refused alert is raised. An update that would need a refused image changes nothing.

  • Offline. When the registry cannot be reached, a server keeps using the images it already verified, and the host agent starts after a reboot without asking the registry.

  • The host agent itself is checked by the installed ohm before every start. An agent whose image does not verify is not started:

    Remote or local
    $ journalctl -u ohm-agent

    gives the reason, and sudo ohm install verifies and pins the agent's image again.

Turning it on for an existing server​

A server installed before image signing keeps taking the newest published images, and raises the Image signing not set up alert each time its host agent starts. Update the package and repair the installation once, on the server:

Remote or local
$ sudo apt-get update
sudo apt-get install --only-upgrade antelao-ohm
sudo ohm install

From then on the server runs a verified release.

Instances with firewall rules or pre-authentication​

Every request to an instance with firewall rules that need the management API, or with pre-authentication, is judged by asking the management API, and a request it cannot judge is refused rather than let through. So while an upgrade restarts the management API, those instances refuse their visitors. The upgrade keeps that window as short as the API's own restart:

  • the management API is recreated before the web server, and the web server is recreated only once the API answers, so the new web server never comes up unable to judge a request;
  • the web server is given three seconds to finish the requests it is serving before it is stopped, instead of waiting for open websocket connections that never finish; browsers reconnect by themselves.

The upgrade's job log says how long it was, for example Protected instances were refusing for 24.5 s while the management API restarted. Their refusal logs show those rows as refused closed: the access check could not answer, not as the rules refusing anyone. Instances without such rules are not affected by the API restarting, only by the web server's own few seconds.

An update with ohm install that also upgrades the master database stops the management API and the console for the schema upgrade and brings them back straight after it, before the rest of the install, so those instances refuse visitors for the upgrade and the API's restart only - seconds, not the whole install. The install's output says how long, for example Protected instances were refusing for 9.0 s while the master database was upgraded and the management API restarted.

Order of operations​

An update can change the master database for good

A release that brings a newer master-database schema upgrades it, and the upgrade cannot be undone by installing the older release again. Roll back refuses such an update. Without a backup of the master database and its key ring from before the update, there is no way back.

  1. Back the server itself up: export the master database from Master data with a passphrase, so the export carries the key ring, and download it, as Backing up the server itself describes. After a schema change this is the only way back.

  2. See what would change:

    Remote or local
    $ ohm server update

  3. Apply it:

    Remote or local
    $ ohm server upgrade

  4. If the new build needs a newer master-database schema, the management API refuses to start against the old one and says so, and the console cannot reach it. Bring the schema forward on the host. The command shows what it will change, asks first, and writes an export of the master database to the backup directory before it changes anything:

    Local only
    $ sudo ohm database upgrade

    --dry-run shows the plan and changes nothing. sudo ohm install does the same upgrade as part of a repair, before it rolls any container, and is the way to bring the server onto a newer antelao-ohm package as well.

  5. Check that the Updates page shows the release you applied, that Core services shows every service running, and that your instances answer.

The console's own certificate needs nothing at update time: the bootstrap agent renews it every day (see The server's certificate and authority).

Rolling back​

Roll back on the Updates page takes the server back one release, to the one it ran before its last update. It is on every edition, and it loses no data: the master database is not touched.

The card says whether it can run, and why not. Press Roll back, type the release to confirm, and press Roll back now. From the command line:

ohm server rollback

It asks first unless you pass --yes. The command goes through the management API, on the server too. When the API is down, the host agent's own Updates page, on port 5202, offers the same rollback. That page cannot see the API's jobs, so use the console while it is up.

What it does and what it leaves alone:

  • The management API, the console and the host agent are recreated on the previous release. What the newer release added disappears from the console.
  • Instances keep running. Those with firewall rules or pre-authentication refuse visitors while the management API restarts.
  • GeoIP and Fail2Ban stay on the versions they run.
  • It goes back one step only.
  • A later sudo ohm install moves the server forward again, without asking.

It is refused:

  • While a job is running or queued. Wait for them to finish.
  • When the update changed the master database's schema. Nothing is lowered or restored for you: see After a schema change.
  • When the previous release's images are no longer on the server. The registry keeps one version, so the copy on the server is the only one. A server keeps the previous release's images from its next update on, about 2 GB, and each update lets the release before that one go. So the first rollback is possible one update after your server reached the release that brought this.
  • When no earlier release is recorded. The next update records one.

After a schema change​

The master database schema upgrade is forward-only

A newer release may upgrade the master database schema. An older build then refuses to start against it, and Roll back refuses the update.

Going back therefore means restoring the master database from before the upgrade, with its key ring, as well as reinstalling the previous version. Without that backup there is no way back.

What that needs is the export from step 1 of the order of operations, or the export the schema upgrade wrote by itself, which carries no key ring (see What an update writes by itself).

Release notes​

Remote or local
$ ohm release-notes

The same notes are on the console's Release notes page, which is last in the menu, below License, and open to every role. They are built into the product itself rather than fetched, so they always describe the version you are actually running and reading them needs no connection to the outside.

What you get is the prose written for the release - what changed and what it means for you - rather than a generated list of commit subjects. Entries are grouped under Breaking, Improvements, Bugfixes and Known Issues, in the console's own words. Every release's notes are also in this manual, on Release notes.

Changes that alter nothing you can see sit under Under the hood, folded away on the page and left out of ohm release-notes unless you ask for them.

The GitHub release carries the same notes above its commit list, so every place agrees.

Instances are not upgraded by this​

server update and server upgrade cover Antelao. Moving an Odoo instance to a newer Odoo major version means migrating its databases, and that is what an instance's Upgrade tab does: see Upgrading an instance to a newer Odoo version. Changing the Version on an instance's Configuration tab rebuilds its image for the new version but leaves its databases as they are (see Changing the Odoo version).

Where the Upgrade tab does not apply, because the license does not carry it or you migrate with tools of your own, a copy is a safe place to try one, and the result comes in beside the original:

  1. Make a copy to try it on: duplicate the instance with the Test or Staging preset, so the copy cannot send mail or run scheduled actions as the original.

  2. Take the database out: back up the copy's database, and download it.

    Remote or localagainst pelmo
    $ ohm instance database backup --instance tissi

  3. Migrate it with Odoo's own upgrade process, outside Antelao.

  4. Bring it in on the new version: create a new instance with the target Version, and on the wizard's Database tab choose Restore an uploaded Odoo backup with the migrated database. Each instance owns its own databases, so the upgraded database goes into a new instance of its own rather than into the original's.

  5. Test it there. When it is right, repeat with a fresh backup of production, then move the names over to the new instance.

The original instance runs on, untouched, throughout: it is the way back until you remove it.

Last updated on