Customer installations

Checklist for installing on a real customer machine. The goal: install without fear, knowing that if anything goes wrong the system goes back to what it was.

Before (prerequisites)

• OS: Ubuntu ≥ 22.04, Debian ≥ 11 or Fedora ≥ 40. Exercised in CI up to Ubuntu 24.04, Debian 12 and Fedora 44: on a newer release the installation goes ahead, but with a warning. What differs between the families: Multi-distribution support.
• Access as a normal user with sudo (not root directly).
• ≥ 5 GB free; port 8069 free (80/443 too with Nginx — unless it is Nginx itself holding them, which is not a conflict).
• A strong admin password decided (never admin in production).
• If the machine already has a PostgreSQL or an important database: no problem, the installer does not touch it — but read The rollback model to know exactly what is protected.
• If you will use wkhtmltopdf: check that the checksum pins are populated (see Security), or the installation will stop on the safe side.

0. Getting invok onto the machine

On a customer machine you install the package, you do not compile: .deb for Ubuntu/Debian, .rpm for Fedora, each with its .sha256 to verify before installing. They drop only the invok command into /usr/bin (plus the vok alias) — no service, no user, no dependency: Odoo is installed by the command, at runtime, when you run it.

Full commands and checksums: README → Install.

If the machine should not be left with the installer on it, use the musl .tar.gz: it is the same executable, you run it where you unpacked it and delete it afterwards.

1. Preview (touching nothing)

invok --config /path/to/customer.env --dry-run

It changes nothing: it shows what would be done and what is already there. Use it to validate the customer's configuration before going ahead. It runs without sudo too, but then some steps cannot inspect the system and the plan comes out incomplete — the installer says so. For the full plan, run it with sudo.

2. Run

sudo invok --config /path/to/customer.env

The run is traced to /var/log/invok.log (ask for it if there is trouble): it exists from the first installation and stays even after a rollback.

You can interrupt with Ctrl-C: the installation rolls itself back and the system returns to what it was.

3. If it fails

No manual intervention needed. If a step fails, the installer performs an automatic rollback: it undoes the executed steps in reverse order and brings the system back to its initial state. Resources that were already there (a database with the same name, a pre-installed PostgreSQL, /opt/odoo, the user's .bashrc) are left intact. Read the error, fix the cause — usually the config or a prerequisite — and run it again: the installer resumes where it stopped, with the same parameters (with different ones it stops and says which field does not match).

Typical cases and what they mean: Verification and troubleshooting.

If the installation had instead already succeeded, a re-run stops on purpose: the uninstall manifest must not be overwritten. To reinstall: sudo invok rollback first, or --force (which archives the previous manifest instead of deleting it).

4. Final check

systemctl status odoo18
journalctl -u odoo18 -n 50 --no-pager

Open http://<host>:8069 (or through Nginx if configured) and log in with the master password.

A second customer on the same machine

If the machine already carries an installation, do not re-run the installer plainly: it would stop, because without a name it means the one that is already there. Name the new one, and give it a port:

sudo invok --instance cliente-x --port 8169

Everything that instance owns is qualified by that name — user, role, database, unit, directory, config, filestore — so the two share nothing but the machine, the packages and the PostgreSQL cluster. sudo invok list shows what a machine carries, and each instance is removed on its own with sudo invok rollback --instance cliente-x. Detail: More than one instance.

Handover to the customer

• The odoo command is available to the installing user: odoo start|stop|restart|status|dev (after source ~/.bashrc). It is deliberately not global — only for that user.
• Config file: /opt/odoo/odoo18/odoo18.conf — it holds the master password, permissions 0640 odoo:odoo. For a named instance, /opt/odoo/odoo-<name>/odoo-<name>.conf.
• Installer log: /var/log/invok.log.
• How to uninstall: sudo invok rollback (or --instance <name> when the machine carries more than one). It works because the manifest (/var/lib/invok/state.json, or /var/lib/invok/instances/<name>.json) stays on disk after a successful installation: it says which artifacts we created and which were already there. Do not remove it — without it, automatic removal is no longer possible.
• If the customer wants HTTPS: sudo certbot --nginx -d domain after the installation. The installer does not configure TLS on purpose — certbot rewrites the vhost itself.

---

The “surgical” promise is what makes it safe to point this installer at a production machine: it leaves no dirty intermediate state and destroys no pre-existing data. The details: The rollback model and Security.