Decide on Odoo install path for v19.x

[JedMeister]

As I am not an Odoo user and I know that both @marcos-mendez & @l-arnold are. So could you guys discuss and suggest the "best" way to install Odoo for v19.x?

My desire would be to make a decision on default Odoo version and install method and stick with that for the whole life-cycle of v19.x. I really don't want to repeat the issues that we had with one of our other releases where we chopped and changed install method between minor version releases (v17.x?).

OTOH keeping the actual Odoo version that we install at build time is less important than the install method - at least IMO.

Considerations OTTOMH:

• life cycle of Odoo - i.e. whether we might need to change versions to retain upstream support - better if we don't but acceptable if we do
• "best effort" support for users to update their Odoo version in place
• "best effort" to support TKLBAM migrations - should always work restoring to the same TKL release (e.g. v19.0 => v19.0); ideally should always work between TKL minor versions (e.g. v19.0 => v19.1). Bonus points if it can manage migration between v18.x => but that is less important, although be good to document...
• Additional stuff we might want to include? IIRC there was a third party project to make migration between versions easier. I have no idea, but maybe that's something worth including OOTB?
• more I haven't thought of...?!?

[marcos-mendez]

Thanks @JedMeister for opening this and assigning us. I'll lay out a recommendation as thoroughly as I can — this is a transition-blocker and I want to give us something concrete to converge on, with enough rationale that @l-arnold, yourself, or anyone from the community can push back where I got it wrong.

Context from my side: PopSolutions has been building on the TKL Odoo appliance for close to a decade, currently operating around 80+ production Odoo instances (including deployments at 4k+ concurrent users), and I've been active in OCA work across several repos. So I have strong opinions shaped by production reality — opinions, not decrees.

One note before the technical content: this issue sits naturally alongside #2096 (Odoo updates and migration tooling). The two are complementary — #2111 decides the shape of the install (layout, version, Python env), and #2096 is where the lifecycle tooling lives, building on @l-arnold's turnkeylinux-odoo-tools. My proposal below is designed to cooperate with that work, not replace it.

1. The structural constraint on version choice

Something worth naming up front for anyone not deep in the Odoo ecosystem: OCA releases modules for even-numbered Odoo versions only — 12, 14, 16, 18, 20. For any TKL appliance whose value benefits from OCA modules (localizations, reporting, workflow helpers, industry modules), this makes version choice structural, not discretionary.

This reframes the question. It's not "Odoo 18 or 19?" — it's Odoo 18 now, Odoo 20 as the in-place upgrade path (expected October 2026). Odoo 19 exists but lives outside the community stack and I would not build a TKL appliance around it.

2. Installation method: source from upstream

Straight from upstream:

git clone --branch 18.0 --depth 1 https://github.com/odoo/odoo /opt/odoo-18

No distribution .deb, no vendor redistributable, no intermediary. Upstream moves, we track when we choose to. This is what every serious Odoo production deployment does and it's what PopSolutions has done on TKL for nearly a decade.

Why not the Odoo-provided .deb from nightly.odoo.com: historically lags Debian releases by months, pinned dependencies block patching workflows, upgrade cadence dictated by Odoo Inc. rather than us. Source wins on every axis that matters for a long-lived appliance.

3. Directory layout — evolving from /opt/odoo to /opt/odoo-N

The current TKL Odoo appliance installs Odoo into /usr/lib/python3/dist-packages/odoo/ — the result of running setup.py install system-wide.

@l-arnold has already done significant work moving away from that location: turnkeylinux-odoo-tools refactors Odoo installs out of the Debian-packaged layout and into /opt/odoo/, which is a much cleaner starting point for appliance lifecycle management. I'd like to propose building directly on that movement with one additional refinement: put the Odoo major version in the path itself.

Why add the version:

1. Parallel installs for migration. An unversioned /opt/odoo/ still only lets one Odoo live on the box at a time. For Odoo 18 → 20 over the v19.x lifecycle — or for the intermediate 16→17→18 hops that @l-arnold's work already addresses — we need both versions coexisting briefly during migration. The new one runs on a staging port while the old one serves production, until the operator validates the cutover.
2. Visual clarity. A sysadmin landing on the box should see immediately whether it's Odoo 16, 18, or 20. The current appliance doesn't give that cue at all; /opt/odoo/ gives it partially; /opt/odoo-18/ gives it fully.

My proposal: a flat, version-explicit layout under /opt/, where the Odoo core and every adjacent module tree are siblings, each tagged with its Odoo major version.

/opt/odoo-18/          # github.com/odoo/odoo @ branch 18.0 (cloned directly)
/opt/odoo-18-venv/     # Python venv, version-specific
/opt/oca-18/           # OCA verticals (opt-in, see section 4)
├── social/
├── e-commerce/
├── l10n-brazil/
└── ...
/opt/custom-18/        # operator's own modules (optional)

/etc/odoo/odoo-18.conf
/var/lib/odoo-18/      # filestore (TKLBAM-critical)
/var/log/odoo-18/
Systemd unit: odoo-18.service

The addons_path in odoo-18.conf composes /opt/odoo-18/addons, /opt/odoo-18/odoo/addons, whichever verticals exist under /opt/oca-18/, and /opt/custom-18/ if present.

When Odoo 20 lands, the operator installs /opt/odoo-20/, /opt/odoo-20-venv/, /opt/oca-20/, /opt/custom-20/ alongside the 18.x set, each with its own service unit on a staging port and its own filestore. Both run in parallel during migration. OpenUpgrade (or odoo-tools for the odd-version intermediate hops) handles the schema migration. The new instance is validated against real data. Only then is Odoo 18 stopped, the port swapped, and the 18.x tree decommissioned.

Attempting the same migration against a single unversioned directory — whether /usr/lib/python3/dist-packages/odoo/ or /opt/odoo/ — means rsync gymnastics, rename-then-regret, or a forced cutover with no rollback. All three are how people lose production data.

Version-explicit paths cost nothing at install time and make the migration story clean. For an appliance whose whole proposition is lifecycle management, this should be the default.

4. OCA verticals — via odoo-tools, surfaced through confconsole

As I noted in #2096, I'd like to see odoo-tools extended to support automated installation of OCA verticals as a first-class capability. This issue is the natural place to define the operator-facing side of that: an interactive confconsole prompt at first boot that lets the operator choose which OCA verticals they want, and triggers odoo-tools to fetch and install them.

Concretely: confconsole presents something like "Would you like to install OCA vertical repositories? [social, e-commerce, l10n-brazil, web, server-tools, account-financial-reporting, ...]". For each selected entry, it invokes odoo-tools install-oca-vertical <name> (or equivalent), which clones the correct branch (18.0 in this case) into /opt/oca-18/<vertical>/ and regenerates addons_path. The same odoo-tools command is then usable post-install for adding verticals later, outside the first-boot flow.

Advantages of this split:

• Keeps the base ISO small and opinion-free.
• Operator curates the vertical set that matches their business — no dead weight.
• The odoo-tools backend is reusable: first boot, manual ops, CI/CD, scripted deploys.
• The same pattern ports cleanly to /opt/oca-20/ when migration happens, so the upgrade story stays symmetric.
• Future OCA vertical additions or deprecations are backend list updates, not ISO rebuilds.

Happy to lead the confconsole inithook part. I've been working inside confconsole already (my fork carries a dhcpcd-ipv6-support branch adding DHCPv4/DHCPv6 dual-stack support), so the surface is familiar. The OCA vertical install logic belongs in odoo-tools per my comment in #2096, and I'd like to coordinate with @l-arnold on that side.

5. Python environment

Drawing directly on @JedMeister's 2024 writeup on PEP 668 ("Python PEP 668 - working with 'externally managed environment'"), which grew out of an earlier conversation of ours about this very appliance:

• System-level Python dependencies installed via apt where Debian packages exist and match (python3-psycopg2, python3-lxml, python3-pillow, python3-reportlab, python3-ldap, python3-babel, etc.).
• venv created with --system-site-packages: python3 -m venv --system-site-packages /opt/odoo-18-venv.
• Odoo's own requirements.txt pinned versions land in the venv on top, overriding where needed.

This gives us Debian security updates on the common libraries, clean version control for Odoo-specific pins, and none of the friction of either pure isolation or --break-system-packages. It's also what you recommended publicly in the blog post, so the appliance would just be operationalizing the pattern you already argued for.

A secondary benefit of moving to /opt/odoo-18-venv/ is that it leaves /usr/lib/python3/dist-packages/ purely for Debian-managed Python packages, restoring a cleaner separation between what apt owns and what the application owns.

As I noted in #2096, some OCA dependencies are notorious for conflicting with system packages — particularly the reporting chain (wkhtmltopdf/weasyprint) and the geoengine stack (GDAL/GEOS/Shapely). The --system-site-packages venv handles most cases well via apt-sourced common libraries and venv-pinned overrides, but those specific stacks may still need case-by-case attention during appliance build. Worth flagging so we're not surprised.

6. TKLBAM profile

The profile should focus on what's data or operator choice, not what's reconstructible from upstream:

• PostgreSQL dump of all Odoo databases
• /var/lib/odoo-18/ (filestore)
• /etc/odoo/odoo-18.conf
• /opt/oca-18/ (the verticals the operator selected)
• /opt/custom-18/ (operator's own modules)

The core (/opt/odoo-18/) and the venv (/opt/odoo-18-venv/) are reconstructible from git clone + pip install -r requirements.txt, so they can be omitted from the backup to keep it lean. Operators who prefer fuller disaster-recovery snapshots can easily include them.

@l-arnold's observation in #2096 that TKLBAM didn't work reliably for 16→17 migration due to differences in the underlying Odoo code is worth taking seriously. The versioned layout helps here by splitting responsibilities cleanly: TKLBAM handles backup/restore within a single Odoo version (where its guarantees hold), and major-version transitions are handled explicitly by odoo-tools/OpenUpgrade as a deliberate operator-driven step. That split removes the expectation that TKLBAM should magically bridge major version gaps — an expectation it was never really designed to meet.

Restore within a TKL minor series (v19.0 → v19.1) is clean as long as the layout stays stable — which is exactly your ask. Restore across TKL majors (v18 → v19) is doable via an explicit migration step (odoo-tools / OpenUpgrade) in the middle, manually triggered. I'd document this rather than automate it; Odoo migrations are risky enough that operators should run them consciously.

7. OpenUpgrade and odoo-tools — complementary migration paths

OCA/OpenUpgrade is the community standard for Odoo version migrations, and it follows the same even-version cadence (16→18, 18→20). @l-arnold's turnkeylinux-odoo-tools covers the odd-version intermediate hops (16→17, 17→18) that OpenUpgrade doesn't. Together they cover the full migration grid.

I'd ship OpenUpgrade under /opt/openupgrade/ (or as a separate switchable branch), and reference odoo-tools in the appliance documentation as the companion tool for operator-driven major-version transitions. Both available but neither active by default.

The versioned layout from section 3 makes both flows natural: Odoo versions and their OCA trees coexist on disk during migration, either tool has access to both codebases at once, the cutover is controlled, and rollback to odoo-18.service is one systemctl call away until the operator decides to remove the old tree.

Open points I'd like @l-arnold, @JedMeister, and the community to weigh in on

1. Confirm Odoo 18 as default, Odoo 20 as the in-place upgrade path inside v19.x.
2. Version-explicit layout (section 3): proposal is to build on @l-arnold's /opt/odoo/ move and add the version to the path (/opt/odoo-18/). Comfortable with that direction, or is there a reason to keep unversioned /opt/odoo/ that I haven't considered?
3. OCA verticals via confconsole + odoo-tools (section 4): does this split of responsibilities work — confconsole as first-boot UI, odoo-tools as the engine? And @l-arnold, are you open to coordinating on the OCA extension work in odoo-tools as tracked in Support easier/more reliable Odoo updates - both for updating Odoo inplace and when migrating Odoo data to newer TurnKey version #2096?
4. External PostgreSQL support on day one: ties into Support for better appliance scalability/HA/clustering support - i.e. make it easier to "split" a single app between separate servers #2097. I think yes, but minimally scoped — a single inithook toggle. The full decoupling discussion belongs there.
5. OpenUpgrade shipping: bundled OOTB as proposed, or recommended-but-separate install instructions?

If we can align on these, I'll draft the appliance build spec as a PR, the confconsole inithook as a separate PR, and coordinate with @l-arnold on the odoo-tools OCA extension per #2096.