From b7eb4bdadbb8ece18382d4b4dae31f3fdf13d7b3 Mon Sep 17 00:00:00 2001 From: Guillermo Rojo Date: Thu, 8 Oct 2026 13:45:52 +0200 Subject: [PATCH 1/2] fix(install): drop on cleanup only a PostgreSQL role this install created The cleanup of a failed PostgreSQL or Odoo + PostgreSQL install dropped the instance's role even when it existed before the run. The role's existence is now read before the plan and the cleanup drops it only when the run created it. Two Spanish literals left in the management views are English keys. --- AGENTS.md | 91 ++++++++++++++++++++++++++ CLAUDE.md | 92 +-------------------------- instance_manager/i18n.py | 2 + instance_manager/workflows/install.py | 8 ++- instance_manager/workflows/manage.py | 6 +- 5 files changed, 103 insertions(+), 96 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dcfe242 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# Odoo Instance Manager — AI Agent Guide (CLAUDE.md) + +Interactive, **root-run** Python CLI to install, maintain, and audit multi-instance **Odoo Community** +servers on the Debian/Ubuntu (apt) family — validated on Ubuntu 24.04, but the tool **detects** the OS +codename, nginx, PostgreSQL, and Odoo major and renders version-correct configuration rather than assuming a +single stack. It never mutates the host directly: every action assembles a command **plan**, previews it, and +applies it only after confirmation. This file is the single authored source of truth for AI agents working +*on* this project. + +## Project boundary & paths + +- **This repository is the project root.** A single Python package, no nested repos. +- `odoo_instance_manager.py` — entry point (root check, UTF-8 console, main menu). +- `instance_manager/` — the package, in strict layers (see `docs/architecture.md`): + - `models.py` — `InstanceConfig`, identifier validation, path derivation. + - `planners.py` — **pure** builders returning `list[Command]` (odoo.conf, systemd, nginx, fail2ban, TLS). + No I/O, no execution. + - `system.py` — execution primitives, existence probes, `preview_commands`/`apply_commands`. + - `prompts.py` — interactive input, file picker, `confirm_with_phrase`. + - `ui.py` — terminal tables and styling. + - `workflows/` — a package split by capability (install, manage, backup_restore, fail2ban, firewall, + services, purge, report, health, diskusage, addons, logrotate, scheduled_backup, …) over a shared + `common.py`; menus, plan assembly, discovery, and the read-only audit. +- `openspec/specs/` — the **behavior source of truth** (one spec per capability). Changes live in + `openspec/changes/`. +- `docs/` — user/operator docs, each with frontmatter. Grown surfaces are grouped into folders + (`docs/operations/`, `docs/security/`); setup/reference/audit pages stay flat at `docs/`; `docs/decisions/` + holds ADRs. The README is the routable map. +- **English is canonical.** The app UI defaults to English, and all docs and specs are English. Spanish is + offered only as an optional UI language through the i18n layer (`instance_manager/i18n.py`): every + operator-facing string goes through `t`/`tf` with the **English text as the source of truth** — never a + hardcoded literal, and never Spanish-first. Docs must quote the **English** UI labels; do not add a new + UI language without adding its i18n catalog. + +## Conventions + +- Python 3.12+, `from __future__ import annotations`, **standard library only** (no third-party runtime deps). +- Files are UTF-8, newlines LF, final newline at EOF. +- Conventional Commits, imperative mood, one logical change per commit. No AI-attribution trailers. +- Match the surrounding code: small functions, early returns, type hints. +- **Keep planners pure** — building a command is not running it. Execution belongs to `system.py`. +- **Quote and validate every operator-supplied value** reaching a shell command or SQL string (use `_quote` + / `shlex.quote` and the identifier validators). Never interpolate raw input. + +## How to work in this project + +- **Non-trivial changes are spec-first.** Capture intent and a short plan before code, and keep a record of + what changed and why. Behavior is specified in `openspec/specs/`; use the OpenSpec `/opsx:*` flow + (`/opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive`) and validate with + `openspec validate --specs`. +- **Preview → confirm → apply is inviolable.** Every host-mutating action must go through a previewed plan; + destructive/data actions must keep their exact phrase confirmation. Do not add a code path that mutates the + system without a plan. (See `docs/decisions/0001-plan-preview-apply-safety.md`.) +- **Keep docs honest.** When behavior changes, update the affected `docs/` page and the README map in the + same change. +- **Keep the root `README.md` current.** It is the friendly front door *and* the routable map: a clear, + friendly description and usage of the utility, the architecture diagram (kept as-is), a supported-platforms + matrix (OS codenames, nginx, PostgreSQL, Odoo majors), and links out to `docs/`. Update it in lockstep with + any behavior, capability, or docs change. +- **Keep the changelog and version in lockstep.** User-facing changes go under `## [Unreleased]` in + `CHANGELOG.md` (Keep a Changelog format) as they land. To cut a release, follow **SemVer**: rename + `[Unreleased]` to `[] - ` (leave a fresh empty `[Unreleased]` on top), bump `version` + in `pyproject.toml` to match, add the `[]` compare/tag link at the bottom, then tag `v`. + Pushing the tag triggers the **Release workflow** (`.github/workflows/release.yml`): it verifies the tag + matches the `pyproject` version, runs the checks, builds the sdist + wheel, and publishes/updates the GitHub + Release with those artifacts and the changelog notes. The tag, the `pyproject` version, and the changelog + heading must always agree (the workflow fails the release if they don't). +- **Secure by default.** Validate input at boundaries, never hardcode secrets, and quote everything that + reaches a shell or SQL. The tool runs as root — assume every input is attacker-controlled. +- **Add dependencies deliberately.** This project is standard-library-only by design; introducing a runtime + dependency is itself a decision worth an ADR — pin it, scan for known CVEs, and justify it. +- **Some actions are irreversible or sensitive** — force-push, history rewrite, secret access, deleting + instances/databases: pause and confirm first. Safe-controls hooks enforce a floor when installed (see + `docs/security/safe-controls.md`). + +## Safe controls + +- Runtime guardrails come from the **eunomai** Claude Code plugin's `PreToolUse` hooks (ask-by-default on + force-push / `rm -rf` / secret access; deny on AI-attribution commit trailers). Fail-open, a floor-raiser, + not a security boundary. +- Static path rules use the native `permissions` baseline in `.claude/settings.json` — see + `docs/security/safe-controls.md`. + +## Checks + +Structural, read-only gates (run from the project root): + +```bash +openspec validate --specs # every capability spec is well-formed +# eunomai docs-check / provenance-check via the installed plugin/CLI +``` diff --git a/CLAUDE.md b/CLAUDE.md index dcfe242..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,91 +1 @@ -# Odoo Instance Manager — AI Agent Guide (CLAUDE.md) - -Interactive, **root-run** Python CLI to install, maintain, and audit multi-instance **Odoo Community** -servers on the Debian/Ubuntu (apt) family — validated on Ubuntu 24.04, but the tool **detects** the OS -codename, nginx, PostgreSQL, and Odoo major and renders version-correct configuration rather than assuming a -single stack. It never mutates the host directly: every action assembles a command **plan**, previews it, and -applies it only after confirmation. This file is the single authored source of truth for AI agents working -*on* this project. - -## Project boundary & paths - -- **This repository is the project root.** A single Python package, no nested repos. -- `odoo_instance_manager.py` — entry point (root check, UTF-8 console, main menu). -- `instance_manager/` — the package, in strict layers (see `docs/architecture.md`): - - `models.py` — `InstanceConfig`, identifier validation, path derivation. - - `planners.py` — **pure** builders returning `list[Command]` (odoo.conf, systemd, nginx, fail2ban, TLS). - No I/O, no execution. - - `system.py` — execution primitives, existence probes, `preview_commands`/`apply_commands`. - - `prompts.py` — interactive input, file picker, `confirm_with_phrase`. - - `ui.py` — terminal tables and styling. - - `workflows/` — a package split by capability (install, manage, backup_restore, fail2ban, firewall, - services, purge, report, health, diskusage, addons, logrotate, scheduled_backup, …) over a shared - `common.py`; menus, plan assembly, discovery, and the read-only audit. -- `openspec/specs/` — the **behavior source of truth** (one spec per capability). Changes live in - `openspec/changes/`. -- `docs/` — user/operator docs, each with frontmatter. Grown surfaces are grouped into folders - (`docs/operations/`, `docs/security/`); setup/reference/audit pages stay flat at `docs/`; `docs/decisions/` - holds ADRs. The README is the routable map. -- **English is canonical.** The app UI defaults to English, and all docs and specs are English. Spanish is - offered only as an optional UI language through the i18n layer (`instance_manager/i18n.py`): every - operator-facing string goes through `t`/`tf` with the **English text as the source of truth** — never a - hardcoded literal, and never Spanish-first. Docs must quote the **English** UI labels; do not add a new - UI language without adding its i18n catalog. - -## Conventions - -- Python 3.12+, `from __future__ import annotations`, **standard library only** (no third-party runtime deps). -- Files are UTF-8, newlines LF, final newline at EOF. -- Conventional Commits, imperative mood, one logical change per commit. No AI-attribution trailers. -- Match the surrounding code: small functions, early returns, type hints. -- **Keep planners pure** — building a command is not running it. Execution belongs to `system.py`. -- **Quote and validate every operator-supplied value** reaching a shell command or SQL string (use `_quote` - / `shlex.quote` and the identifier validators). Never interpolate raw input. - -## How to work in this project - -- **Non-trivial changes are spec-first.** Capture intent and a short plan before code, and keep a record of - what changed and why. Behavior is specified in `openspec/specs/`; use the OpenSpec `/opsx:*` flow - (`/opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive`) and validate with - `openspec validate --specs`. -- **Preview → confirm → apply is inviolable.** Every host-mutating action must go through a previewed plan; - destructive/data actions must keep their exact phrase confirmation. Do not add a code path that mutates the - system without a plan. (See `docs/decisions/0001-plan-preview-apply-safety.md`.) -- **Keep docs honest.** When behavior changes, update the affected `docs/` page and the README map in the - same change. -- **Keep the root `README.md` current.** It is the friendly front door *and* the routable map: a clear, - friendly description and usage of the utility, the architecture diagram (kept as-is), a supported-platforms - matrix (OS codenames, nginx, PostgreSQL, Odoo majors), and links out to `docs/`. Update it in lockstep with - any behavior, capability, or docs change. -- **Keep the changelog and version in lockstep.** User-facing changes go under `## [Unreleased]` in - `CHANGELOG.md` (Keep a Changelog format) as they land. To cut a release, follow **SemVer**: rename - `[Unreleased]` to `[] - ` (leave a fresh empty `[Unreleased]` on top), bump `version` - in `pyproject.toml` to match, add the `[]` compare/tag link at the bottom, then tag `v`. - Pushing the tag triggers the **Release workflow** (`.github/workflows/release.yml`): it verifies the tag - matches the `pyproject` version, runs the checks, builds the sdist + wheel, and publishes/updates the GitHub - Release with those artifacts and the changelog notes. The tag, the `pyproject` version, and the changelog - heading must always agree (the workflow fails the release if they don't). -- **Secure by default.** Validate input at boundaries, never hardcode secrets, and quote everything that - reaches a shell or SQL. The tool runs as root — assume every input is attacker-controlled. -- **Add dependencies deliberately.** This project is standard-library-only by design; introducing a runtime - dependency is itself a decision worth an ADR — pin it, scan for known CVEs, and justify it. -- **Some actions are irreversible or sensitive** — force-push, history rewrite, secret access, deleting - instances/databases: pause and confirm first. Safe-controls hooks enforce a floor when installed (see - `docs/security/safe-controls.md`). - -## Safe controls - -- Runtime guardrails come from the **eunomai** Claude Code plugin's `PreToolUse` hooks (ask-by-default on - force-push / `rm -rf` / secret access; deny on AI-attribution commit trailers). Fail-open, a floor-raiser, - not a security boundary. -- Static path rules use the native `permissions` baseline in `.claude/settings.json` — see - `docs/security/safe-controls.md`. - -## Checks - -Structural, read-only gates (run from the project root): - -```bash -openspec validate --specs # every capability spec is well-formed -# eunomai docs-check / provenance-check via the installed plugin/CLI -``` +@AGENTS.md diff --git a/instance_manager/i18n.py b/instance_manager/i18n.py index 7052e6f..b6a0af3 100644 --- a/instance_manager/i18n.py +++ b/instance_manager/i18n.py @@ -862,6 +862,8 @@ def tf(template: str, *args: object, **kwargs: object) -> str: "invalid data_dir. Use an absolute path.": "data_dir no válido. Usa una ruta absoluta.", "[WARN] Role {} is also used by: {}. Its databases are not selected by owner and the role is not dropped.": "[WARN] El rol {} también lo usa: {}. Sus bases de datos no se seleccionan por dueño y el rol no se elimina.", # --- labels moved to English (phase 5) --- + 'TLS certificate': 'Certificado TLS', + 'Additional package': 'Paquete adicional', 'Owner config Odoo': 'Propietario del config de Odoo', 'Owner config dir': 'Propietario del directorio de config', 'Owner fullchain': 'Propietario del fullchain', diff --git a/instance_manager/workflows/install.py b/instance_manager/workflows/install.py index 80d0643..cb230fd 100644 --- a/instance_manager/workflows/install.py +++ b/instance_manager/workflows/install.py @@ -36,6 +36,7 @@ from ..system import ( Command, apply_commands, + db_role_exists, detect_arch, detect_cpu_count, detect_host_python, @@ -598,8 +599,10 @@ def install_db_only() -> None: ensure_remote_access = ask_bool( 'Configure listen_addresses and pg_hba for remote access?', True ) + # Dropped on failure only if this run creates it: an existing role is reused. + role_is_new = not db_role_exists(config.db_user) commands = plan_db_setup(config, ensure_remote_access=ensure_remote_access) - _execute_install_with_cleanup(commands, config, cleanup_db_role=True) + _execute_install_with_cleanup(commands, config, cleanup_db_role=role_is_new) def install_odoo_and_db() -> None: @@ -608,6 +611,7 @@ def install_odoo_and_db() -> None: 'Enable the Odoo service to start on boot?', True, ) + role_is_new = not db_role_exists(config.db_user) commands: list[Command] = [] commands.extend(_plan_runtime(config)) # Odoo and PostgreSQL on one host talk over loopback: nothing is opened to the @@ -626,4 +630,4 @@ def install_odoo_and_db() -> None: commands.extend(_maybe_plan_logrotate(config)) - _execute_install_with_cleanup(commands, config, cleanup_db_role=True) + _execute_install_with_cleanup(commands, config, cleanup_db_role=role_is_new) diff --git a/instance_manager/workflows/manage.py b/instance_manager/workflows/manage.py index 1362623..279b0d4 100644 --- a/instance_manager/workflows/manage.py +++ b/instance_manager/workflows/manage.py @@ -36,7 +36,7 @@ user_exists, wkhtmltopdf_version, ) -from ..ui import level_tag, level_text, render_table, title +from ..ui import level_tag, level_text, prompt_label, render_table, title from .addons import show_addon_inventory from .backup_restore import ( _backup_instance, @@ -145,7 +145,7 @@ def _show_detected_state_view( ["OK" if path_exists(data_dir) else "MISSING", "Data dir", data_dir], ] cert_mode, cert_ok = _detect_certificate_mode(config) - status_rows.append(["OK" if cert_ok else "MISSING", "Certificado TLS", cert_mode]) + status_rows.append(["OK" if cert_ok else "MISSING", t('TLS certificate'), cert_mode]) if db_error: status_rows.append(["MISSING", "DB listing", tf("connection/query failure -> {}", db_error)]) @@ -301,7 +301,7 @@ def _install_python_packages_in_instance_venv(config: InstanceConfig) -> None: extra_lines: list[str] = [] print(level_text("INFO", 'Add more packages (one per line). Empty Enter to finish.')) while True: - line = input("Paquete adicional: ").strip() + line = input(f"{prompt_label('Additional package')}: ").strip() if not line: break extra_lines.append(line) From 7c293d4894ad6110ee442bb9665ea07f22891def Mon Sep 17 00:00:00 2001 From: Guillermo Rojo Date: Thu, 8 Oct 2026 13:45:52 +0200 Subject: [PATCH 2/2] docs: refresh against the code, diagrams in semantic colours, AGENTS.md A coherence audit of README and docs against the code: pages follow the menu's submenus; the install, neutralisation, validation and paths pages state what the code does; the glossary defines and links instead of repeating; the fail2ban page no longer suggests ufw enable without SSH. Diagrams use five shared colour classes (step, ask, guard, stop, data), defined once in docs/architecture.md: the main menu, the layers, the plan flow, the per-version install, the neutralised copy and the ban scope. AGENTS.md is the agent instruction file, CLAUDE.md a one-line bridge, and CI checks the docs with eunomai v0.6.1. --- .github/workflows/ci.yml | 2 +- AGENTS.md | 6 +- CHANGELOG.md | 11 + README.md | 50 +++-- docs/architecture.md | 84 +++++--- docs/configuration-reference.md | 25 ++- docs/glossary.md | 66 +++--- docs/installation.md | 48 +++-- docs/language.md | 7 +- docs/operations/addon-inventory.md | 11 +- docs/operations/disk-usage.md | 4 +- docs/operations/health-check.md | 8 +- docs/operations/instance-management.md | 279 +++++++++++++------------ docs/operations/log-rotation.md | 6 +- docs/operations/scheduled-backups.md | 6 +- docs/platforms.md | 15 +- docs/security/firewall.md | 9 +- docs/security/safe-controls.md | 4 +- docs/security/security-fail2ban.md | 38 ++-- docs/server-audit.md | 8 +- 20 files changed, 402 insertions(+), 285 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f9b65a6..9e05c2c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,7 +64,7 @@ jobs: uses: actions/checkout@v7 with: repository: grojof/eunomai - ref: v0.4.0 + ref: v0.6.1 path: .eunomai - name: Docs check diff --git a/AGENTS.md b/AGENTS.md index dcfe242..1a7e427 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# Odoo Instance Manager — AI Agent Guide (CLAUDE.md) +# Odoo Instance Manager — AI Agent Guide (AGENTS.md) Interactive, **root-run** Python CLI to install, maintain, and audit multi-instance **Odoo Community** servers on the Debian/Ubuntu (apt) family — validated on Ubuntu 24.04, but the tool **detects** the OS @@ -54,8 +54,8 @@ applies it only after confirmation. This file is the single authored source of t - **Keep docs honest.** When behavior changes, update the affected `docs/` page and the README map in the same change. - **Keep the root `README.md` current.** It is the friendly front door *and* the routable map: a clear, - friendly description and usage of the utility, the architecture diagram (kept as-is), a supported-platforms - matrix (OS codenames, nginx, PostgreSQL, Odoo majors), and links out to `docs/`. Update it in lockstep with + friendly description and usage of the utility, a diagram of what it does (in the colour classes of + `docs/architecture.md`, *Diagram conventions*), a link to the supported-platforms matrix in `docs/platforms.md`, and links out to `docs/`. Update it in lockstep with any behavior, capability, or docs change. - **Keep the changelog and version in lockstep.** User-facing changes go under `## [Unreleased]` in `CHANGELOG.md` (Keep a Changelog format) as they land. To cut a release, follow **SemVer**: rename diff --git a/CHANGELOG.md b/CHANGELOG.md index 3254ebe..33004d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,12 @@ All notable changes to this project are documented here. The format is based on ### Changed +- **Docs refreshed against the code**, with diagrams in shared semantic colours (`docs/architecture.md`, + *Diagram conventions*): the main menu, the layers, the plan flow (the phrase is asked before the preview), the + per-version install, the neutralised copy, and what each fail2ban jail blocks. Pages follow the menu's + submenus; the glossary defines terms and links to their pages instead of repeating lists. +- `AGENTS.md` is the agent instruction file (`CLAUDE.md` is a one-line `@AGENTS.md` bridge), and CI checks the + docs with eunomai v0.6.1. - **Interface text is English throughout**, with Spanish only through the catalog: about twenty Spanish labels left in the code (report headers, certificate states, prompts) are now English keys. The catalog is written English → Spanish, the direction it is read; written the other way and inverted, it silently merged English @@ -37,6 +43,11 @@ All notable changes to this project are documented here. The format is based on ### Fixed +- **A failed install could drop a PostgreSQL role it had not created.** The cleanup of the PostgreSQL and + Odoo + PostgreSQL installs dropped the instance's role even when it existed before; it now drops it only when + this run created it. +- The fail2ban page suggested `ufw enable` without allowing SSH first; it now points to the Firewall menu, which + does. - **Passwords were visible to every local user.** Each database password went into the command text (`PGPASSWORD=… psql`), so it was in the arguments of the running step, which `ps` shows any user (another instance's Odoo user included), and it was printed in the plan preview and in a failed step's error, as were diff --git a/README.md b/README.md index dbbdff0..1e5ad8c 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,10 @@ tool is for you. If you use Odoo's SaaS/Online or a managed host, you don't need ## What it does for you -- **Set up a new Odoo site in minutes** — creates the system user, clones Odoo, builds the virtualenv, writes - the config and systemd service, and optionally sets up PostgreSQL, Nginx, and TLS. +- **Set up a new Odoo site, any version from 12 to 19** — creates the system user, clones official Odoo or + OCA's **OCB**, builds the virtualenv with the Python and setuptools that version needs (installing a matching + Python with uv when the server's own cannot build it), writes the config and systemd service, and optionally + sets up PostgreSQL, Nginx, and TLS. - **Run many sites on one server** — each instance is isolated (its own service, ports, config, and database), all derived from a name, so they don't collide. - **Keep them secure by default** — strong random master/DB passwords, a hidden database manager @@ -22,8 +24,10 @@ tool is for you. If you use Odoo's SaaS/Online or a managed host, you don't need writes version-correct config (see [Supported platforms](docs/platforms.md)). - **Keep them healthy** — a one-look health check (service, HTTP, database, disk), disk-usage reports, and log rotation. -- **Never lose data** — manual or **scheduled automatic backups**, plus restore and duplicate, all with - retention. +- **Never lose data** — manual or **scheduled automatic backups** with retention per database, plus restore + and duplicate. +- **Copy production safely** — a restored or duplicated database is **neutralised** before any Odoo can see it: + no mail leaves, no cron, payment, EDI or webhook runs as production, and a check confirms it. - **Know what you have** — a read-only whole-server audit and an addon inventory (Odoo core / OCA / custom, with versions and which are installed). @@ -52,25 +56,39 @@ sudo python3 odoo_instance_manager.py Then pick an action from the main menu — for example **Installation menu** to create a new Odoo site, or **Manage instances** to manage an existing one. Every action shows its full command plan and waits for your -confirmation before touching the system. +confirmation before touching the system; a destructive action also asks you to type a confirmation phrase. ```mermaid flowchart LR - op["You (root)"] --> menu["Main menu"] - menu --> install["Install / provision"] - menu --> manage["Manage instances
(backup · health · logs · addons)"] - menu --> sec["Security
(Fail2ban · UFW)"] - menu --> audit["Server audit (read-only)"] - install & manage & sec --> plan["Plan → preview → confirm → apply"] - plan --> host["Ubuntu host"] - audit -. "read-only" .-> host + op(["You (root)"]) --> menu{"Main menu"} + menu --> install["Install
Odoo 12–19 · PostgreSQL"] + menu --> manage["Manage instances
status · backups · duplicate"] + menu --> services["Instance services
start · stop · restart"] + menu --> sec["Fail2ban · Firewall"] + menu --> remove["Remove instances"] + menu --> report[("Server report
read-only")] + install & manage & services & sec & remove --> plan["Plan → preview"] + plan --> confirm{"Confirm"} + confirm -- yes --> apply["Apply in order"] + confirm -- no --> menu + classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a + classDef ask fill:#fef3c7,stroke:#d97706,color:#78350f + classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d + classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d + classDef data fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class op,install,manage,services,plan,apply step + class menu,confirm ask + class sec guard + class remove stop + class report data ``` ## Documentation **Set up** -- [Installing and provisioning instances](docs/installation.md) — install modes, ports, Nginx, TLS. +- [Installing and provisioning instances](docs/installation.md) — install modes, Odoo version and core, Python, + ports, Nginx, TLS. - [Configuration reference](docs/configuration-reference.md) — every field, default, and derived path. - [What it offers & supported platforms](docs/platforms.md) — capabilities and the OS/nginx/PostgreSQL/Odoo support matrix. @@ -78,7 +96,7 @@ flowchart LR **Daily operations** ([docs/operations/](docs/operations/)) - [Managing existing instances](docs/operations/instance-management.md) — status, updates, services, - backup/restore, duplicate, removal. + backup/restore, duplicate and neutralise, removal. - [Instance health check](docs/operations/health-check.md) — read-only check of service, HTTP, database, disk. - [Scheduled backups](docs/operations/scheduled-backups.md) — unattended backups on a systemd timer. - [Disk usage & retention](docs/operations/disk-usage.md) — instance footprint and pruning old backups. @@ -103,7 +121,7 @@ flowchart LR ## Contributing -Read [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md). Non-trivial changes are spec-first via the +Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). Non-trivial changes are spec-first via the OpenSpec flow; keep planners pure and never weaken a safety control. Security policy: [SECURITY.md](SECURITY.md). ## License diff --git a/docs/architecture.md b/docs/architecture.md index 071f393..7a6a712 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,7 +4,7 @@ title: "Architecture" description: "The layered design of Odoo Instance Manager and the plan → preview → confirm → apply flow." tags: [architecture, design] audience: [contributor, operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Architecture @@ -18,26 +18,32 @@ passes an operator gate. ```mermaid flowchart TD - entry["odoo_instance_manager.py
entry point · root check · main menu"] - workflows["workflows/
menus · plan assembly · discovery · audit"] - subgraph inputs["Input & presentation"] - prompts["prompts.py
ask/choose · file picker · phrase confirm"] - ui["ui.py
tables · styling"] + entry(["odoo_instance_manager.py
root check · language · main menu"]) + workflows["workflows/
one module per capability:
prompts · plan assembly · discovery · audit"] + subgraph pure["Pure — no I/O"] + models["models.py
InstanceConfig · validators · paths"] + support[("support.py
per-version facts")] + neutralise[("neutralise.py
neutralisation SQL")] + planners["planners.py
builders → list[Command]"] end - models["models.py
InstanceConfig · identifier validation · paths"] - planners["planners.py
PURE builders → list[Command]"] - system["system.py
run() · existence probes · preview/apply"] - host["Ubuntu host
apt · systemd · nginx · postgres · fail2ban"] + subgraph io["Input and output"] + prompts["prompts.py · ui.py · i18n.py
ask · tables · English → Spanish"] + end + system{{"system.py
preview · confirm · apply · probes"}} + host(["Ubuntu host
apt · systemd · nginx · PostgreSQL · fail2ban · ufw"]) entry --> workflows workflows --> prompts - workflows --> ui - workflows --> models workflows --> planners - planners --> models - workflows --> system - planners -. "list[Command]" .-> system + planners --> models & support & neutralise + workflows -- "list[Command]" --> system system --> host + classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a + classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d + classDef data fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class entry,workflows,planners,models,prompts step + class support,neutralise data + class system guard ``` | Layer | Module | Responsibility | Side effects | @@ -51,6 +57,7 @@ flowchart TD | Execution | `instance_manager/system.py` | `run()`, existence checks, `preview_commands`, `apply_commands` | Runs shell | | Input | `instance_manager/prompts.py` | Interactive prompts, file picker, phrase confirmation | Reads stdin | | Render | `instance_manager/ui.py` | Terminal tables, tags, colors | Prints | +| Language | `instance_manager/i18n.py` | The English → Spanish catalog, `t`/`tf` | None | ## The core flow @@ -58,24 +65,47 @@ Every host-mutating action follows the same pipeline (specified as the `executio ```mermaid flowchart LR - collect["Collect &
validate input"] --> build["Build plan
(planners)"] - build --> preview["Preview
numbered commands"] - preview --> confirm{"Confirm?
+ phrase if
destructive"} - confirm -- no --> menu["Back to menu"] - confirm -- yes --> root{"root?"} - root -- no --> err["Refuse"] - root -- yes --> apply["Apply in order"] - apply -- error during install --> cleanup["Best-effort
cleanup residues"] + collect["Collect and
validate input"] --> build["Build the plan
(planners)"] + build --> phrase{"Destructive?
type the phrase"} + phrase -- wrong --> menu(["Back to menu"]) + phrase -- right or not needed --> preview["Preview
secrets masked"] + preview --> confirm{"Confirm?"} + confirm -- no --> menu + confirm -- yes --> apply["Apply in order
(root only)"] + apply -- a step fails --> stop(["Stop at that step
report it by name"]) + stop -- install --> cleanup["Clean the install's residues"] + cleanup --> menu + classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a + classDef ask fill:#fef3c7,stroke:#d97706,color:#78350f + classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d + classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d + class collect,build,apply step + class phrase,confirm ask + class preview,cleanup guard + class stop,menu stop ``` - **Commands** are `system.Command(description, command, env, display)`. A plan is just a `list[Command]`. Secrets never go in `command`: a password or a file holding one travels in `env` (the step's environment, readable only by root, unlike its arguments, which `ps` shows every user), and `display` is what the preview shows instead, with the secrets masked. A failed step is reported by its description. -- `preview_commands` renders the whole plan before anything runs; `apply_commands` runs it, stopping on error - (and re-raising so install flows can clean up). -- Destructive actions add `confirm_with_phrase` — the operator must type an exact phrase naming the - operation and instance. +- Destructive actions first ask for `confirm_with_phrase` — the operator types an exact phrase naming the + operation and instance — and only then show the plan. +- `preview_commands` renders the whole plan before anything runs; `apply_commands` runs it in order and stops + at the first failing step. An install that fails, or is interrupted with Ctrl+C, then removes what it created + and returns to the menu. + +## Diagram conventions + +Diagrams in these pages share five colour classes, each also stated by the node's label: + +| Class | Meaning | `classDef` | +|-------|---------|------------| +| `step` | an action | `fill:#dbeafe,stroke:#2563eb,color:#1e3a8a` | +| `ask` | a decision or a confirmation | `fill:#fef3c7,stroke:#d97706,color:#78350f` | +| `guard` | a safeguard: a check, a validation, a rollback | `fill:#dcfce7,stroke:#16a34a,color:#14532d` | +| `stop` | an end: refused, failed, removed | `fill:#fee2e2,stroke:#dc2626,color:#7f1d1d` | +| `data` | data or facts: a database, a file, a report | `fill:#ede9fe,stroke:#7c3aed,color:#4c1d95` | See [ADR 0001](decisions/0001-plan-preview-apply-safety.md) for the rationale, and the [configuration reference](configuration-reference.md) for the paths every plan derives from an instance name. diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index a04f001..4d49442 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -4,7 +4,7 @@ title: "Configuration reference" description: "InstanceConfig fields, defaults, validation patterns, and every path derived from an instance name." tags: [reference, configuration, paths] audience: [operator, contributor] -updated: 2026-07-04 +updated: 2026-10-08 --- # Configuration reference @@ -50,12 +50,21 @@ instance name. See [Installing and provisioning instances](installation.md#produ ## Validation -Identifiers are checked by `validate_identifiers()` **before** any command is built: +Every value that reaches a shell command, SQL or a configuration file is checked by `validate_identifiers()` +**before** any command is built, and the prompts ask again for a refused value (patterns in +`instance_manager/models.py`): -| Value | Pattern | Meaning | -|-------|---------|---------| +| Value | Accepted | Meaning | +|-------|----------|---------| | `instance` | `^[a-z][a-z0-9_]{0,31}$` | Lowercase first letter, then `[a-z0-9_]`, max 32 chars. | | `db_user` | `^[a-z_][a-z0-9_]{0,62}$` | PostgreSQL identifier, max 63 chars. | +| database names | `^[a-zA-Z0-9][a-zA-Z0-9_.-]{1,62}$` | Odoo's own `DBNAME_PATTERN`: no leading symbol, no quote, `$` or space. | +| `version` | `12`–`19`, optionally `.0` | A version the [support matrix](platforms.md#odoo-versions) knows. | +| `repo_branch` | a plain ref name | Letters, digits, `.`, `_`, `/`, `-`; no `..`, never an option. | +| `domain` | DNS labels, optional leading `*.` | What nginx `server_name` and a certificate CN accept. | +| `db_host` | host name, IP or socket directory | Empty means Odoo's local socket. | +| `app_server_ip` | an IPv4 or IPv6 address | Written as `/32` or `/128` in `pg_hba`. | +| `core` / `python` / `data_dir` | `odoo` or `ocb` / `3.N` / an absolute path | | ## Derived paths @@ -76,6 +85,12 @@ For an instance named `` with domain ``: | `ssl_key_file` | `/.server.key` | | `ssl_intermediate_file` | `/.intermediate.crt` | | `ssl_fullchain_file` | `/.fullchain.crt` | +| `managed_data_dir` | `/var/lib/odoo/` (new installs' `data_dir`) | +| `logrotate_config_file` | `/etc/logrotate.d/odoo-` | +| `nginx_access_log` / `nginx_error_log` | `/var/log/nginx/.access.log` / `.error.log` | +| scheduled backup | `/usr/local/sbin/odoo-backup-.sh`, `odoo-backup-.service` / `.timer` | +| fail2ban | `/etc/fail2ban/jail.d/odoo-auth-.local`, shared filter `/etc/fail2ban/filter.d/odoo-auth.conf` | +| uv interpreters (shared) | `/opt/odoo-python` | `domain_token` is the lowercased domain with `*` → `wildcard` and any other unsafe character replaced by `_`. @@ -93,7 +108,7 @@ an `addons_path` of `/odoo/addons,/addons-oca,/addons-custom`, > **Security note:** the recommended defaults are secure — `list_db = False`, a strong random master > password, a `dbfilter`, and `db_sslmode = require` for remote databases. The operator can still choose the > convenient options (exposed manager, chosen password) after an explicit warning, and the current posture is -> surfaced by the **Status ▸ Security & production** view and the server-audit report. +> surfaced by the **Status: security & production** view and the server-audit report. ## Related diff --git a/docs/glossary.md b/docs/glossary.md index 4f7abf4..0dc2f85 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -4,60 +4,62 @@ title: "Glossary" description: "Domain vocabulary used across Odoo Instance Manager: instance, filestore, jail, neutralize, and more." tags: [glossary, reference, vocabulary] audience: [operator, contributor] -updated: 2026-07-03 +updated: 2026-10-08 --- # Glossary -Terms as they are used in this project. +Terms as they are used in this project. Each entry defines the term and links to the page that holds its details. - **Instance** — one deployed Odoo Community environment, identified by a name that derives its user, home, config, service, ports, and Nginx/TLS paths (see [configuration reference](configuration-reference.md)). - Multiple instances co-exist on one host ("multi-instance"). - -- **Multi-instance** — running several independent Odoo instances on the same server, each with its own - service, ports, config, and (usually) database, isolated by name-derived paths. + Several instances co-exist on one host. - **Base instances directory** — `/opt/odoo`; each subdirectory is an instance home. -- **Instance home** — `/opt/odoo/`, containing `odoo/` (the cloned source), `addons-oca/`, +- **Instance home** — `/opt/odoo/`, containing `odoo/` (the cloned core), `addons-oca/`, `addons-custom/`, and the `venv/`. -- **Plan** — an ordered `list[Command]` an action builds *before* executing anything. Each `Command` is a - `(description, command)` pair. Plans are previewed, then applied. See [architecture](architecture.md). +- **Core** — the Odoo repository an instance runs: official Odoo (`odoo/odoo`) or OCA's **OCB** (`OCA/OCB`, the + same branches with backported fixes). Chosen at install; a replica runs its source's core. + +- **Support matrix** — the per-version facts the install follows: each Odoo version's Python range, the Python + uv installs when the host's cannot build it, the setuptools pin and the PostgreSQL floor + ([supported platforms](platforms.md#odoo-versions)). + +- **uv** — the tool that installs a Python interpreter into `/opt/odoo-python` when the host's `python3` + cannot build an Odoo version; one pinned release, checked against its published SHA-256. + +- **Plan** — an ordered `list[Command]` an action builds *before* executing anything. A `Command` has a + description, the command, the secrets it needs (in its environment, never in the command) and what the + preview shows. See [architecture](architecture.md). - **Planner** — a **pure** function in `planners.py` that builds a plan and performs no I/O or execution. -- **Filestore** — Odoo's on-disk store for attachments/binaries, under - `/filestore/` (default `data_dir` is `/.local/share/Odoo`). Backed up and moved - alongside the database. +- **data_dir** — Odoo's data directory: filestores and sessions. New installs set it to + `/var/lib/odoo/`, outside the home; an instance without `data_dir` in its `odoo.conf` uses Odoo's + default, `/.local/share/Odoo`. -- **data_dir** — Odoo's data directory (from the config, or the default under the instance home) that contains - the filestore. +- **Filestore** — Odoo's on-disk store for attachments, `/filestore/`. Backed up, restored + and copied alongside its database. -- **Copied vs moved** — restore/duplicate semantics. **Copied** regenerates the target's `database.uuid` so it - is a distinct database; **moved** keeps the UUID. +- **Copied vs moved** — restore/duplicate semantics. **Copied** gives the target its own identity + (`database.uuid`, `database.secret`, creation date); **moved** keeps it. -- **Neutralize** — make a copied database unable to act as production: crons, mail (servers off, credentials - dropped, a mail sink so `odoo.conf`'s server is never used), fetchmail, payment providers, carriers, OAuth, - calendar tokens, webhooks, IAP, EDI/SII modes, queued jobs and the base URL. Checked afterwards; see - `instance_manager/neutralise.py` for each rule and its source. +- **Neutralize** — make a copied database unable to act as production, before any Odoo can see it, and check it + afterwards. The rules are listed in [instance management](operations/instance-management.md#restore-and-duplicate--copied-vs-moved). -- **database.uuid** — Odoo's per-database identifier stored in `ir_config_parameter`; regenerated in copied - mode. +- **Mail sink** — the one active outgoing mail server a neutralised database keeps, pointing at a host that does + not resolve, so Odoo never falls back to the `smtp_server` of `odoo.conf`. -- **Jail** — a Fail2ban unit that watches a log and bans offending IPs. This tool creates a per-instance - `odoo-auth-` jail plus base jails (`sshd`, `nginx-http-auth`, `nginx-botsearch`, `recidive`). +- **Jail** — a Fail2ban unit that watches a log and bans offending IPs: the base jails and a per-instance + `odoo-auth-` jail ([Fail2ban protection](security/security-fail2ban.md)). - **Real client IP** — the actual visitor IP, as opposed to the proxy/gateway IP. Behind Nginx, Odoo must log - the real client IP (via forwarded headers) or Fail2ban would ban your own infrastructure. See - [Fail2ban security](security/security-fail2ban.md). + the real client IP (via forwarded headers) or Fail2ban would ban your own infrastructure. - **Phrase confirmation** — typing an exact phrase (e.g. `DELETE `) to authorize a destructive - action, on top of the normal confirm step. - -- **Total purge** — the most destructive action: removes an instance plus its Linux user, logs, filestore - root, the databases its role owns (or named like it), and PostgreSQL roles. Gated by `DELETE-ALL `. + action; asked before the plan is shown. -- **Capability spec** — an OpenSpec specification under `openspec/specs//spec.md` describing a - slice of behavior as requirements and scenarios; the behavior source of truth. +- **Total purge** — the most destructive action: an instance with its Linux user, logs, jail, databases and + roles, gated by `DELETE-ALL ` ([instance management](operations/instance-management.md#removing-an-instance)). diff --git a/docs/installation.md b/docs/installation.md index b6708b4..44d631e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -4,7 +4,7 @@ title: "Installing and provisioning instances" description: "Run the manager and provision an Odoo instance, PostgreSQL, or both, including Nginx and TLS." tags: [installation, provisioning, nginx, tls] audience: [operator] -updated: 2026-07-04 +updated: 2026-10-08 --- # Installing and provisioning instances @@ -53,18 +53,29 @@ derived path): ### Odoo version, Python and setuptools -You type the Odoo version (12–19); the branch defaults to `.0`. Each version accepts a range of Python -versions (see [Supported platforms](platforms.md)), and the tool checks the host's `python3` against it before -the plan: - -- **Inside the range** → the venv is built with the host `python3`. -- **Outside it** (e.g. Odoo 14 on Ubuntu 24.04's Python 3.12, or Odoo 17 on Debian 11's 3.9) → the plan - installs **uv** (one pinned release, checked against its published SHA-256) and the CPython the matrix names - into `/opt/odoo-python` (root-owned, readable by the instances), and builds the venv with it. -- Odoo 16–19 never use a host Python 3.10: their requirements pin a gevent for 3.10 that pip cannot build. +You type the Odoo version (12–19) and choose the core; the branch defaults to `.0`. Before the plan is +shown, the tool decides which Python builds the virtualenv: + +```mermaid +flowchart LR + version["Odoo version
12–19"] --> core{"Core
Odoo or OCB"} + core --> fit{"Can the host's
python3 build it?"} + fit -- yes --> host["Host python3"] + fit -- no --> uv["uv (pinned, SHA-256 checked)
installs the matrix's Python
into /opt/odoo-python"] + host & uv --> venv["venv + pip, wheel,
the version's setuptools,
requirements.txt"] + classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a + classDef ask fill:#fef3c7,stroke:#d97706,color:#78350f + classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d + class version,host,venv step + class core,fit ask + class uv guard +``` -setuptools is pinned per version: `<58` up to Odoo 13 (`vatnumber` uses `use_2to3`) and `<81` up to Odoo 16 -(they import `pkg_resources`, which setuptools 81 removed). Odoo 12's `pyldap` is replaced by `python-ldap`. +The host's `python3` "can build" a version when it is inside the version's Python range, is not 3.10 for Odoo +16–19 (their requirements pin a gevent for 3.10 that pip cannot build) and, for Odoo 12 and 13, which state no +maximum, is not newer than 3.8. So on Ubuntu 24.04 (Python 3.12) the host builds Odoo 15–19, and Odoo 12–14 get +uv's Python 3.8. The ranges, the fallback interpreters and the setuptools pins (`<58` up to Odoo 13, `<81` up to +Odoo 16) are in the [support matrix](platforms.md#odoo-versions). ### Port suggestion @@ -76,7 +87,9 @@ override the suggestion. The tool ensures the instance's PostgreSQL role exists with `LOGIN CREATEDB`, **creating it only if missing** and never changing an existing role's password. For a **remote** DB host it skips role creation (no admin -credentials assumed) and only validates the configured user's login. +credentials assumed) and only validates the configured user's login. When the plan installs PostgreSQL, it also +checks the server is at least the Odoo version's documented floor (13 for Odoo 19, 12 for 14–18) and stops if +it is older. ## Production hardening @@ -100,7 +113,7 @@ explicit warning. - **`db_sslmode`.** For a **remote** DB host it defaults to `require` (offered `require` / `verify-full` / `prefer` / `disable`, with a warning for the cleartext-capable modes). Local hosts are left untouched. - **wkhtmltopdf.** Odoo PDF reports (invoices, quotations, …) require wkhtmltopdf. A three-way choice: - the **patched 0.12.6** build (recommended, checksum-verified, selected by the detected OS codename), the + the **patched 0.12.6** build (recommended, checksum-verified, selected by the detected OS codename; amd64), the **distribution package** (un-patched, reduced report fidelity), or **skip** (warned that PDF reports will fail until it is installed). @@ -129,9 +142,10 @@ For HTTPS you pick a certificate strategy: ## If an install fails -If applying an install plan errors partway, the tool runs a **best-effort cleanup** of that instance's -residues (service, config, home, Nginx vhosts, SSL dir, the new data dir while it holds no filestore, and — -when the run created it — the DB role) so you can retry cleanly. The original error is then re-raised. +If an install plan fails partway, or you interrupt it with Ctrl+C, the tool runs a **best-effort cleanup** of +that instance's residues — service, config, home, Nginx vhosts, SSL dir, the new data dir while it holds no +filestore, and the DB role when this run created it (a role that already existed is kept) — and returns to the +menu, so you can retry cleanly. ## Related diff --git a/docs/language.md b/docs/language.md index e69612a..4b30328 100644 --- a/docs/language.md +++ b/docs/language.md @@ -4,7 +4,7 @@ title: "Interface language (English / Spanish)" description: "Choose the UI language at startup or with the OIM_LANG environment variable." tags: [i18n, language, ui] audience: [operator] -updated: 2026-07-04 +updated: 2026-10-08 --- # Interface language @@ -14,7 +14,7 @@ language: the strings live in English in the code, and Spanish is a full transla ## Choosing the language -- **At startup** — when it starts, the tool asks **Español / English**, then shows the menu. +- **At startup** — the tool asks **Idioma / Language** (English is the default), then shows the menu. - **Non-interactively** — set the `OIM_LANG` environment variable to skip the prompt: ```bash @@ -29,7 +29,8 @@ language: the strings live in English in the code, and Spanish is a full transla Everything user-facing renders in the chosen language: menus, prompts, section titles, table headers and string cells, command/plan descriptions, interpolated status messages, and the yes/no shortcut (`Y/n` in English, `S/n` in Spanish). Anything without a Spanish translation falls back to its English source, so -nothing breaks. The translation catalog lives in `instance_manager/i18n.py` and is easy to extend. +nothing breaks. The catalog lives in `instance_manager/i18n.py`, English → Spanish; a test fails when an interface string has +no Spanish entry. ## Related diff --git a/docs/operations/addon-inventory.md b/docs/operations/addon-inventory.md index 55629e8..957f488 100644 --- a/docs/operations/addon-inventory.md +++ b/docs/operations/addon-inventory.md @@ -4,12 +4,12 @@ title: "Addon inventory" description: "List an instance's addon modules by origin with versions, and which are installed." tags: [addons, modules, inventory] audience: [operator] -updated: 2026-07-04 +updated: 2026-10-08 --- # Addon inventory -From **Manage instances → Addon inventory**, the tool lists an instance's addon modules — read-only. +From **Manage instances → Status & health → Addon inventory**, the tool lists an instance's addon modules — read-only. ## What it shows @@ -33,14 +33,15 @@ only the available modules. The inventory also audits the **Python packages the addons declare** via each manifest's `external_dependencies['python']` (read safely as a literal, no code execution). For each declared package it -shows which addons require it and whether it **imports in the instance venv** (`OK` / `MISSING`) — so you can +shows which addons require it and whether the instance venv has it (`OK` / `MISSING`) — checked as Odoo does, +by distribution name first (`python-stdnum`, `pdfminer.six`), then as an importable module — so you can spot addon dependencies that aren't installed yet (a common cause of errors, e.g. after duplicating an instance). This audit is included in the export. ## Show only installed, or all -After checking a database, the tool asks **"Show only installed modules (instead of all)?"** (default yes) — -handy because the full list is long. Only-installed hides not-installed modules and any origin group left +After checking a database, the tool asks **"Show only installed modules (instead of all)?"** (default yes), +since the full list is long. Only-installed hides not-installed modules and any origin group left empty; choose *no* to keep the complete inventory. ## Export (optional) diff --git a/docs/operations/disk-usage.md b/docs/operations/disk-usage.md index a2ecc2c..ed4b30b 100644 --- a/docs/operations/disk-usage.md +++ b/docs/operations/disk-usage.md @@ -4,12 +4,12 @@ title: "Disk usage and backup retention" description: "See an instance's disk footprint and prune old backups by retention count." tags: [disk, backups, retention, maintenance] audience: [operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Disk usage and backup retention -From **Manage instances → Disk usage and cleanup**, the tool shows an instance's disk footprint and prunes +From **Manage instances → Status & health → Disk usage and cleanup**, the tool shows an instance's disk footprint and prunes old backups. ## Show disk usage (read-only) diff --git a/docs/operations/health-check.md b/docs/operations/health-check.md index 34641e8..8fcf8a8 100644 --- a/docs/operations/health-check.md +++ b/docs/operations/health-check.md @@ -4,12 +4,12 @@ title: "Instance health check" description: "A read-only check of an instance: service, HTTP, database, and disk." tags: [health, monitoring, maintenance] audience: [operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Instance health check -From **Manage instances → Health check**, the tool runs a **read-only** check and reports +From **Manage instances → Status & health → Health check**, the tool runs a **read-only** check and reports whether the instance is actually working — not just whether its files exist. ## What it checks @@ -17,9 +17,9 @@ whether the instance is actually working — not just whether its files exist. | Check | Healthy when | How | |-------|--------------|-----| | **Odoo service** | the systemd service is active | `systemctl is-active` (+ autostart state) | -| **HTTP local** | the instance answers on its HTTP port | stdlib `urllib` GET to `127.0.0.1:` (`/web/health` → `/web/login` → `/`); any 2xx/3xx counts | +| **HTTP local** | the instance answers on its HTTP port | stdlib `urllib` GET to `127.0.0.1:` (`/web/health` → `/web/login` → `/`); any status below 500 counts as answering | | **DB connection** | the database is reachable | `psql SELECT 1` with the instance's own config credentials | -| **Disco (home / data dir)** | the filesystem is below 90% used | `df -Ph`; ≥ 90% is flagged | +| **Disk (home)** / **Disk (data dir)** | the filesystem is below 90% used | `df -Ph`; ≥ 90% is flagged | Each row is tagged healthy or a problem. If the service is active but HTTP does not answer, the check warns to look at the Odoo log; if the service is down, it points you to *Instance services*. diff --git a/docs/operations/instance-management.md b/docs/operations/instance-management.md index 4dda68e..f527d37 100644 --- a/docs/operations/instance-management.md +++ b/docs/operations/instance-management.md @@ -1,195 +1,206 @@ --- type: how-to title: "Managing existing instances" -description: "Day-2 operations: status, config updates, services, backup/restore, duplicate, and removal." -tags: [management, backup, restore, services, lifecycle] +description: "Day-2 operations: status, configuration updates, services, backup, restore, duplicate and neutralise, removal." +tags: [management, backup, restore, neutralise, services, lifecycle] audience: [operator] -updated: 2026-07-04 +updated: 2026-10-08 --- # Managing existing instances -Once an instance exists under `/opt/odoo`, the **Manage instances** and **Instance services** menus -handle day-2 operations. Instances are discovered automatically; you may also type a known name. +Once an instance exists under `/opt/odoo`, **Manage instances** handles its day-2 operations and **Instance +services** (main menu) starts and stops services. Instances are discovered automatically; you may also type a +known name. -The management menu is grouped into submenus — **Status & health**, **Configuration**, and **Backups & -duplication** — plus a top-level **Delete instance**. +**Manage instances** groups its actions into three submenus — **Status & health**, **Configuration**, +**Backups & duplication** — plus **Delete instance**. This page follows that order. -## Status and inspection +## Status & health -Status is **on-demand**: the management menu no longer prints every status table on each iteration. Instead it -offers four selectable entries: +The status views are shown on demand: - **Status: locations & names** — the instance's expected paths and derived names. -- **Status: detected resources** — the detected-state table: Linux user, home, config file, systemd service - (present + active), DB role, data dir, and TLS certificate mode (self-signed / custom-CA / external / - Let's Encrypt / incomplete / not configured). Optionally connect to PostgreSQL to list databases for - validation — the listing is **scoped to the instance's DB role** (databases owned by it or named after it), - not every database on the server. +- **Status: detected resources** — Linux user, home, config file, systemd service (present and active), DB + role, data dir, and TLS certificate mode (self-signed / custom CA / custom external / Let's Encrypt / + incomplete / not configured). Optionally connects to PostgreSQL to list the databases its role owns or that + are named like it. - **Status: config values** — useful keys read from the instance's `odoo.conf`. -- **Status: security & production** — the production-posture view (below). +- **Status: security & production** — the posture checks below. + +Other entries of this submenu have their own pages: [Health check](health-check.md), +[Addon inventory](addon-inventory.md) and [Disk usage and cleanup](disk-usage.md). **Check a copy is +neutralised** is described under [neutralisation](#restore-and-duplicate--copied-vs-moved). ### Security & production posture -**Status: security & production** flags each posture check `OK` / `WARN` / `INFO` with a reason, read from the -instance's `odoo.conf` plus host facts (no mutation): +Each check is flagged `OK` / `WARN` / `INFO` with a reason, read from the instance's `odoo.conf` and host facts; +nothing is changed. The [server report](../server-audit.md) shows the same checks for every instance. - **Database manager (`list_db`)** — exposed vs disabled. +- **dbfilter** — set vs unset. - **Master / DB passwords** — guessable when they equal the instance name; a **hashed** master password is - treated as `OK`. + `OK`. - **wkhtmltopdf** — presence and version (patched vs un-patched). - **workers** — sizing against the detected CPU count. -- **`db_sslmode`** — for a remote DB host; local hosts are treated as `OK`. -- **dbfilter** — set vs unset. +- **`db_sslmode`** — for a remote DB host; a local host is `OK`. +- **`proxy_mode`** — must be `True` behind Nginx. + +## Configuration -## Updating configuration +### Update existing configuration -**Update existing configuration** rewrites the instance config, systemd unit, and (optionally) the Nginx -vhost with new values — but first it **backs up** the current config, unit, and vhosts into one private -timestamped directory under `/var/backups//config_preupdate/`. The service's autostart state is -preserved. +Rewrites the instance's `odoo.conf` and systemd unit with new values, and optionally its Nginx vhost. First it +**backs up** the current config, unit and vhosts into one private timestamped directory under +`/var/backups//config_preupdate/`. - The current `odoo.conf` is **merged**, not replaced: `addons_path`, `data_dir`, `logfile`, `http_interface` and `without_demo` keep their value, and every key the tool does not write (`smtp_*`, `server_wide_modules`, `db_name`, …) is carried over. -- **Nothing is reinstalled**: no apt, clone or pip run (pip could move setuptools under an Odoo that needs it - pinned). +- **Nothing is reinstalled** — no apt, clone or pip run — so the venv's pinned setuptools stays as it is. - The Odoo version is read from the instance's checkout and the domain from its vhost. -- The passwords are kept unless you choose to set new ones; a new DB password is also set on the local role. -- A running service is **restarted**, so the change is live when the plan ends. +- Passwords are kept unless you choose to set new ones; a new DB password is also set on the local role. +- A running service is **restarted**, so the change is live when the plan ends. Autostart is left as it was. -## Health check +To go back, copy the files from the `config_preupdate/` directory and restart the service. -**Health check** runs a read-only check of the instance — systemd service, local HTTP -response, database connectivity, and disk usage — flagging any problems. See -[Instance health check](health-check.md). +### Other configuration actions -## Service control +- **Repair instance Nginx logs** recreates the per-instance access/error logs with their ownership + (`www-data:adm`, mode `640`) and reopens Nginx's logs. +- **Log rotation** — see [Log rotation](log-rotation.md). +- **Install Python packages in the venv** installs into the instance's virtualenv from a requirements file or an + inline package list, running pip as the instance user. -**Instance services** lists instance services with their run state and autostart state, and offers start, -stop, restart, enable-autostart, and disable-autostart. Each action runs the single matching `systemctl` -command through the preview/confirm/apply flow. +## Backups & duplication -## Backups +> **Credentials are asked once per session:** the first data action that needs a database connection asks for +> host, port, user and password (without echo); later actions offer to reuse them. -**Create backup** exports the database and/or filestore into a timestamped file in your chosen backup -directory: +### Backups + +**Create backup** exports the database and/or filestore into the backup directory you choose: - Database → `pg_dump -Fc` → `----.dump` - Filestore → gzipped tar → `----.filestore.tar.gz` -The name carries the database, so retention keeps N backups of each database. The backup directory is made -private (`700`) and the files are readable by root only: a dump holds password hashes, API keys and mail or -payment secrets. - -**Scheduled backups** sets up unattended backups on a systemd timer — see [Scheduled backups](scheduled-backups.md). - -> **Credentials are collected once per session:** the first data action (backup / restore / duplicate / -> delete) that needs a database connection prompts for host/port/user/password; subsequent actions offer to -> reuse them. Passwords are read without echo. - -## Restore and duplicate — copied vs moved - -Both **Restore backup** and **Duplicate instance** apply Odoo's migration semantics and require an exact -confirmation phrase (`RESTORE ` / `DUPLICATE `): - -- **Copied (new UUID on target)** — gives the target its own `database.uuid`, `database.secret` and creation - date, as Odoo's own copy does, so it is a distinct database from the source. -- **Moved (keep UUID)** — keeps the identity (the database "moves"). -- **Neutralize** (optional, recommended) — makes the copy unable to act as production. It follows Odoo's own - `neutralize.sql` (16.0–19.0) on every version from 12 to 19, plus the OCA modules a Spanish or queue-based - instance runs: crons off (except Odoo's autovacuum and queue_job's cleanup), mail servers off with their - credentials dropped, fetchmail off, and one active **mail sink** (`invalid:1025`) so Odoo never falls back to - the `smtp_server` of `odoo.conf`; payment providers, external carriers and their production mode, OAuth, - calendar tokens, webhooks, IAP, SII/TicketBAI/EDI/Peppol production modes and queued jobs; `web.base.url` - points at the target. The plan then **checks** that nothing can still act on the outside and stops if - something can. - -A copy cannot be picked up by a running Odoo before it is neutralised. An Odoo's cron worker lists every -database its role owns, whatever the `dbfilter`. So a duplicated database stays owned by `postgres` until it is -neutralised, and only then is handed to its role. A restore stops the instance's service while the copy is -restored and neutralised. - -A module update switches crons back on: **Check a copy is neutralised** (in *Status & health*) lists, read-only, -what in a database can still act on the outside. - -Guardrails: restore refuses to overwrite an existing target **database**; an existing target **filestore** -requires an explicit overwrite confirmation, and is then moved aside to `.replaced-` -rather than deleted. The restored files are handed to the instance user. +The name carries the database, so retention keeps N backups of each database +([Disk usage and backup retention](disk-usage.md)). The directory is private (`700`) and the files are readable +by root only: a dump holds password hashes, API keys and mail or payment secrets. +**Scheduled backups** run the same backup on a systemd timer — see [Scheduled backups](scheduled-backups.md). + +### Restore and duplicate — copied vs moved + +**Restore backup**, **Duplicate database** and **Duplicate instance** ask how the copy relates to its source, +and each asks for its confirmation phrase (`RESTORE ` / `DUPLICATE `): + +- **Copied (new UUID on target)** — the target gets its own `database.uuid`, `database.secret` and creation + date, as Odoo's own copy does. +- **Moved (keep UUID)** — the target keeps its identity: the database "moves". +- **Neutralize** (recommended) — the copy cannot act as production. It follows Odoo's own `neutralize.sql` + (16.0–19.0) on every version from 12 to 19, plus the OCA modules a Spanish or queue-based instance runs: + - crons off, except Odoo's autovacuum and queue_job's cleanup; queued jobs held; + - outgoing mail servers off with their credentials dropped, fetchmail off, templates' fixed servers cleared, + and one active **mail sink** (`invalid:1025`) so Odoo never falls back to the `smtp_server` of `odoo.conf`; + - payment providers, external carriers and their production mode, OAuth providers; + - Google and Microsoft calendar tokens, webhooks, IAP accounts; + - SII, TicketBAI, EDI proxy and Peppol in test mode; + - website domain and CDN cleared, `web.base.url` pointing at the target, the "neutralised" banner and flag. + + The rules, each with its source, are in `instance_manager/neutralise.py`. + +A copy is never visible to a running Odoo before it is neutralised. An Odoo's cron worker lists every database +its role owns, whatever the `dbfilter`, so a duplication goes this way: + +```mermaid +flowchart LR + seed[("Copy the database
owned by postgres")] --> identity["Copied mode:
new identity"] + identity --> neutralise["Neutralise
one statement"] + neutralise --> check{"Anything left
that acts outside?"} + check -- yes --> stop(["Stop the plan"]) + check -- no --> handover["Hand the database
to the target role"] + handover --> start["Start the
target service"] + classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a + classDef ask fill:#fef3c7,stroke:#d97706,color:#78350f + classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d + classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d + classDef data fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class identity,start step + class check ask + class neutralise,handover guard + class stop stop + class seed data +``` + +A **restore** creates the database with the credentials you give, so it stops the instance's service while the +copy is restored and neutralised, and starts it again afterwards. + +A module update switches crons back on. **Check a copy is neutralised** (in *Status & health*) lists, read-only, +what in a database can still act on the outside, rule by rule, and whether the mail sink is in place. + +Restore refuses to overwrite an existing target **database**. An existing target **filestore** needs an explicit +overwrite, and is then moved aside to `.replaced-`, not deleted; the restored files are +handed to the instance user. ### Duplicate instance — replica or refresh -*Duplicate instance* is **existence-aware and end-to-end** (local PostgreSQL; for a remote DB use Backup + -Restore). You pick the **copy method**: *pg_dump → restore* (robust, reassigns ownership to the target role — -recommended for **production → development** with different DB users) or a fast *template* copy, which the -tool only allows when the target role already owns the source database (a template copy keeps the source role -as owner of every table). - -- **Target does not exist → replica:** the tool provisions the whole target instance — system user, home, Odoo - checkout at the **source's version**, virtualenv, `odoo.conf`, systemd service, and optionally Nginx — - following the **same prompts as a fresh install** (secrets, `list_db`, `dbfilter`, workers, `db_sslmode`, - wkhtmltopdf), with **auto-suggested non-colliding internal ports**. When it fronts Nginx you must give a - **domain not already used by another instance** — instances share ports 80/443 and Nginx routes by - `server_name`, so a duplicate domain would be silently ignored and the replica unreachable. It then seeds the - target with the source database (+ filestore), optionally **replicates the source venv's Python packages** - (so addon dependencies beyond `requirements.txt` are present), applies copied/moved + neutralize, and starts - it. -- **Target exists → refresh in place:** the tool stops the target service, replaces its database and filestore - from the source, applies the semantics, and restarts — **without** recreating its config or service. This is - the "keep a dev environment up to date with production" flow. The target's database is dropped only when it - belongs to the target's own role (from its `odoo.conf`) and you confirm the overwrite; the source instance or - database can never be the target. - -The filestore always lands under the **target** instance's data directory. The template method closes the -source to new sessions, terminates its sessions (brief disconnect), copies, and reopens it even if the copy -fails; the dump method reads the source live. - -Every seeded database is **isolated to its owner** (`CONNECT` revoked from `PUBLIC`, granted to the owning -role) so an instance's role can't reach other instances' databases, and the target **data dir is owned by the -target user** so Odoo can create its `sessions`/`filestore`. +*Duplicate instance* needs a local PostgreSQL; for a remote database use Backup and Restore. You pick the copy +method: **pg_dump → restore** (re-owns every object to the target role; recommended) or a fast **template** +copy, which keeps the source role as owner of every table and is therefore refused whenever the target role +differs from the source database's owner. + +- **Target does not exist → replica.** The tool provisions the whole instance: system user, home, the + **source's core** (Odoo or OCB) at its branch, a virtualenv built with the Python the version needs on this + host, `odoo.conf` with its own data dir, systemd service, and optionally Nginx — following the same prompts as + a fresh install, with free internal ports suggested. With Nginx, the domain must not be served by another + vhost already. The replica's database role is named after its database, so a replica is always seeded with + the pg_dump copy. It can also install the source venv's extra Python packages. +- **Target exists → refresh in place.** The tool stops the target service, replaces its database and filestore + from the source, applies the semantics, and restarts it, without recreating its config or service. The + target's database is dropped only when it belongs to the target's own role (from its `odoo.conf`) and you + confirm the overwrite; the source instance or database can never be the target. + +Every seeded database is **restricted to its owner** (`CONNECT` revoked from `PUBLIC`, granted to the owning +role), and the target's data dir is owned by the target user. ### Duplicate database -**Duplicate database** copies just a database (no instance provisioning), with the same copy method and -copied/moved + neutralize semantics, and an optional filestore copy under the current instance's data -directory. It touches no service or config. If the target database already exists it asks for an explicit -overwrite, and it refuses a target database owned by another role. Local PostgreSQL only. +Copies one database within the instance, with the same copy methods and semantics and an optional filestore +copy into the instance's data dir. It touches no service or config, asks before overwriting an existing target +database, and refuses one owned by another role. Local PostgreSQL only. -## Repairing Nginx logs & venv packages +## Instance services -- **Repair instance Nginx logs** recreates the per-instance access/error logs with correct ownership - (`www-data:adm`, mode `640`) and reopens Nginx logs. -- **Log rotation** configures and queries a system `logrotate` policy for the instance's Odoo log — see - [Log rotation](log-rotation.md). -- **Install Python packages in the venv** installs into the instance virtualenv from a selected requirements - file or an inline package list, running pip as the instance user. -- **Addon inventory** lists modules by origin (core/OCA/custom) with versions and installed state — see - [Addon inventory](addon-inventory.md). -- **Disk usage and cleanup** shows the instance footprint and prunes old backups by retention — see - [Disk usage and backup retention](disk-usage.md). +**Instance services** (main menu) lists the instance services with their run and autostart state, and offers +start, stop, restart, enable autostart and disable autostart — each the single matching `systemctl` command, +previewed and confirmed. ## Removing an instance -Two levels, both phrase-gated: +Two levels, both phrase-gated and asked before the plan is shown: | Action | Removes | Phrase | |--------|---------|--------| | **Delete instance** (in *Manage instances*) | Service, backup timer, config, home, Nginx vhosts, SSL; optionally the database and one database's filestore | `DELETE ` | -| **Remove instances** (main menu → total purge) | Everything above **plus** the Linux user, logs, fail2ban jail, filestore root, the instance's databases, and the PostgreSQL roles | `DELETE-ALL ` | +| **Remove instances** (main menu → total purge) | Everything above **plus** the Linux user, Odoo and Nginx logs, the fail2ban jail, the filestore root, the instance's databases, and its PostgreSQL roles | `DELETE-ALL ` | + +Neither removes the instance's logrotate policy (`/etc/logrotate.d/odoo-`). -**Delete instance** keeps the filestores you did not ask to delete. Without a `data_dir` in `odoo.conf`, Odoo -keeps them inside the instance home, so the plan first moves the data dir to +**Delete instance keeps the filestores you did not ask to delete.** An instance installed with +`data_dir = /var/lib/odoo/` keeps its data dir where it is. An older instance without a `data_dir` +keeps its filestores inside the home, so the plan first moves its data dir to `/var/backups//kept-data-dir-` and only then removes the home. -The total purge selects the databases its DB role owns and the one named exactly like the instance (plus those -found in the filestore and any you add). Databases whose name merely starts with the instance name (`shop2`, -`shop_eu` when purging `shop`) are listed as **not selected**; add them yourself if they belong to it. When -another instance connects with the same DB role, the purge says so, selects nothing by owner and keeps the role. Without -admin DB access it performs local cleanup only (skipping DB/role deletion). See the -[removal spec](../../openspec/specs/instance-removal/spec.md) for the full contract. +The **total purge** selects the databases the instance's DB role owns and the one named exactly like the +instance, plus those found in its filestore root and any you add. Databases whose name merely starts with the +instance name (`shop2`, `shop_eu` when purging `shop`) are listed as **not selected**; add them yourself if they +belong to it. When another instance connects with the same DB role, the purge says so, selects nothing by owner +and keeps the role. Without admin DB access it performs the local cleanup only. It removes the filestore root +(`/filestore`), not the rest of the data dir. The full contract is the +[removal spec](../../openspec/specs/instance-removal/spec.md). ## Related -- [Installation & provisioning](../installation.md) -- [Fail2ban security](../security/security-fail2ban.md) +- [Installing and provisioning instances](../installation.md) - [Configuration reference](../configuration-reference.md) +- [Fail2ban protection](../security/security-fail2ban.md) diff --git a/docs/operations/log-rotation.md b/docs/operations/log-rotation.md index 97dc4e5..718b970 100644 --- a/docs/operations/log-rotation.md +++ b/docs/operations/log-rotation.md @@ -4,12 +4,12 @@ title: "Log rotation" description: "Configure and query system logrotate for an instance's Odoo log." tags: [logs, logrotate, maintenance] audience: [operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Log rotation -From **Manage instances → Log rotation**, the tool configures and inspects a **system `logrotate`** +From **Manage instances → Configuration → Log rotation**, the tool configures and inspects a **system `logrotate`** policy for an instance's Odoo log (`/var/log/odoo/.log`). ## Configure @@ -30,7 +30,7 @@ rotation policy in place. ### Obsolete `logrotate` conf key -Odoo's built-in `logrotate` option was **removed in Odoo 13**, so the generated `odoo.conf` no longer sets it. +Odoo's built-in `logrotate` option was **removed in Odoo 13**; the generated `odoo.conf` does not set it. If an older instance's `odoo.conf` still has a `logrotate` key, Configure detects it (it is an ignored no-op) and offers to delete the line — no restart needed. diff --git a/docs/operations/scheduled-backups.md b/docs/operations/scheduled-backups.md index fd3425e..a5607db 100644 --- a/docs/operations/scheduled-backups.md +++ b/docs/operations/scheduled-backups.md @@ -4,12 +4,12 @@ title: "Scheduled backups" description: "Run automatic backups of an instance on a systemd timer, with retention." tags: [backups, systemd, timer, automation] audience: [operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Scheduled backups -From **Manage instances → Scheduled backups**, the tool sets up **unattended** backups of an instance on +From **Manage instances → Backups & duplication → Scheduled backups**, the tool sets up **unattended** backups of an instance on a systemd timer. ## Configure scheduled backup @@ -21,7 +21,7 @@ Installs, for `odoo-backup-`: (`pg_restore --list`), optionally tars the filestore, then prunes that database's backups to your retention count; - a **service** (`oneshot`, `UMask=0077`) that runs the script; -- a **timer** with your schedule — **Daily** (02:30), **Weekly** (Sun 03:00), or **Monthly** (day 1, 03:30) — +- a **timer** with your schedule — **Daily** (02:30), **Weekly** (Sunday 03:00), or **Monthly** (day 1, 03:30) — with `Persistent=true` so a missed run catches up after downtime. You choose the database, destination directory, whether to include the filestore, and how many backups to keep. diff --git a/docs/platforms.md b/docs/platforms.md index 2dc5daa..e913817 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -4,7 +4,7 @@ title: "What the utility offers & supported platforms" description: "Capability overview and the OS / nginx / PostgreSQL / Odoo support matrix, plus what is out of scope." tags: [reference, platforms, support, capabilities] audience: [operator, contributor] -updated: 2026-07-04 +updated: 2026-10-08 --- # What the utility offers & supported platforms @@ -16,12 +16,12 @@ server, always through a previewed **plan → confirm → apply** flow. Capabili | Area | What you get | |------|--------------| -| Provisioning | Odoo-only, PostgreSQL-only, or both; isolated system user + venv per instance; systemd unit; Nginx (HTTP/HTTPS); TLS (self-signed / your certs / external Let's Encrypt). | +| Provisioning | Odoo 12–19, official Odoo or OCB; Odoo-only, PostgreSQL-only, or both; isolated system user + venv per instance, built with the Python each version needs (uv when the host's cannot); systemd unit; Nginx (HTTP/HTTPS); TLS (self-signed / your certs / external Let's Encrypt). | | Secure defaults | Strong random master/DB passwords, `list_db = False`, a `dbfilter`, and `db_sslmode = require` for remote databases — each recommended but an **informed, warned choice**. | | Reports (PDF) | Optional **wkhtmltopdf** install: the checksum-verified Qt-patched 0.12.6 build, a distro fallback, or skip. | | Performance | `workers`/memory limits derived from the host's CPU and RAM, with operator override. | | Security | Fail2ban jails (SSH, Nginx, per-instance Odoo), a UFW firewall baseline, TLS management. | -| Operations | Health check, disk usage & retention, log rotation, addon inventory, manual and scheduled backups, restore, duplicate. | +| Operations | Health check, disk usage & retention, log rotation, addon inventory, manual and scheduled backups, restore, duplicate — copies neutralised before any Odoo sees them, and a check of a copy's neutralisation. | | Audit | A read-only whole-server report, including a per-instance **production-posture** summary. | ## Version-adaptive configuration @@ -35,7 +35,7 @@ assuming a single stack: | nginx version | `nginx -v` | `listen … ssl http2` (nginx < 1.25.1) vs `http2 on;` (≥ 1.25.1) | | Odoo major | provided at install | `gevent_port` (≥ 16) vs `longpolling_port` (≤ 15); Nginx `/websocket` vs `/longpolling/poll`; `without_demo` (≤ 18); Python and setuptools | | Host `python3` | `python3 -c sys.version_info` | host venv when it can build the version, else uv's interpreter | -| PostgreSQL version | `SHOW server_version` | `scram-sha-256` support check (audit signal) | +| PostgreSQL server | `server_version_num`, when the plan installs PostgreSQL | stops below the Odoo version's floor | | CPU / RAM | `nproc`, `/proc/meminfo` | derived `workers` and memory limits | ## Support matrix @@ -45,17 +45,18 @@ assuming a single stack: | OS family | Debian/Ubuntu (**apt**) | Package steps target apt. A non-apt OS is detected and warned, not driven blindly. | | Ubuntu | 22.04 (jammy), 24.04 (noble) | Validated primary targets. Newer releases work; the wkhtmltopdf table maps noble → the jammy build. | | Debian | 11 (bullseye), 12 (bookworm) | wkhtmltopdf assets pinned for both. | -| nginx | 1.18 → 1.25+ | HTTP/2 directive form chosen by detected version. `tools/verify_ops_configs.py` runs `nginx -t` on the generated vhosts with Ubuntu 24.04's nginx 1.24. `proxy_cookie_flags` is written from 1.19.8. | +| nginx | 1.18 → 1.25+ | HTTP/2 directive form chosen by detected version; `proxy_cookie_flags` written from 1.19.8. `tools/verify_ops_configs.py` runs `nginx -t` on the generated vhosts with the nginx the host distribution ships (1.24 on Ubuntu 24.04). | | PostgreSQL | 13+ | Local drops use `dropdb --force` (13+); Odoo's own floor per version is below. Every supported Ubuntu/Debian ships 13 or newer. | | Odoo Community | 12 → 19 | Per-version interpreter, setuptools, config keys — see the table below. Official Odoo or OCB. | | wkhtmltopdf | 0.12.6.1-3 (patched) | jammy/noble, bookworm, bullseye assets, each SHA-256-pinned; other codenames use the distro package or skip. | +| CPU architecture | x86_64 (amd64), aarch64 | The pinned uv exists for both; an Odoo version that needs uv's Python cannot be installed on another architecture. The patched wkhtmltopdf assets are amd64 only (use the distro package elsewhere). | ## Odoo versions Python ranges are those Odoo declares; a maximum marked *derived* is the newest interpreter bucket the branch's `requirements.txt` declares (only Odoo 19 states one outright). The fallback interpreter is the one uv installs -when the host's cannot build the version. Facts kept in `instance_manager/support.py`, as in the sibling -odoo_dwg project, which built and started every version on Ubuntu 24.04. +when the host's cannot build the version. The facts are declared once, in `instance_manager/support.py`; +`tools/verify_install_runtime.py` builds a venv for a given Odoo checkout with them and starts it. | Odoo | Python | Fallback (uv) | setuptools | PostgreSQL floor | Notes | |------|--------|---------------|------------|------------------|-------| diff --git a/docs/security/firewall.md b/docs/security/firewall.md index 4e9c6ed..b1cc81d 100644 --- a/docs/security/firewall.md +++ b/docs/security/firewall.md @@ -4,7 +4,7 @@ title: "Firewall (UFW)" description: "Install and manage a UFW firewall baseline for an Odoo server." tags: [security, firewall, ufw] audience: [operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Firewall (UFW) @@ -12,7 +12,7 @@ updated: 2026-07-03 From the main menu **Firewall (UFW)**, the tool installs and manages a UFW firewall for the server. It shows `ufw status verbose` each time you enter. -## Configure a secure UFW baseline +## Install / configure secure baseline Applies a secure baseline: @@ -30,9 +30,8 @@ Applies a secure baseline: ## Other operations - **Allow a port** — `ufw allow /`. -- **Delete a rule (by number)** — lists numbered rules and deletes one, only if that number still shows the - same rule when the plan runs. fail2ban adds its bans at the top of the list, so the numbers can shift while you - read; without the check, deleting "#5" could delete the SSH allow. +- **Delete a rule (by number)** — lists the numbered rules and deletes one only if that number still shows the + same rule when the plan runs: fail2ban adds its bans at the top of the list, which shifts the numbers. - **Enable / Disable UFW**. ## Relationship with Fail2ban diff --git a/docs/security/safe-controls.md b/docs/security/safe-controls.md index c837c0f..b3864f4 100644 --- a/docs/security/safe-controls.md +++ b/docs/security/safe-controls.md @@ -4,7 +4,7 @@ title: "Safe controls" description: "Runtime guardrails (eunomai PreToolUse hooks) and the recommended permissions baseline for this repo." tags: [safe-controls, hooks, security, permissions] audience: [contributor] -updated: 2026-07-03 +updated: 2026-10-08 --- # Safe controls @@ -36,7 +36,7 @@ safety gate to ask before your shell runs a matching command. ## Recommended permissions baseline Static path rules use Claude Code's native `permissions`, already seeded in -[`../.claude/settings.json`](../../.claude/settings.json): +[`.claude/settings.json`](../../.claude/settings.json): ```json { diff --git a/docs/security/security-fail2ban.md b/docs/security/security-fail2ban.md index 77454af..cf349dc 100644 --- a/docs/security/security-fail2ban.md +++ b/docs/security/security-fail2ban.md @@ -4,7 +4,7 @@ title: "Fail2ban protection" description: "Install a secure base, protect Odoo instances per jail, verify real client IPs, and operate bans." tags: [security, fail2ban, hardening] audience: [operator] -updated: 2026-07-03 +updated: 2026-10-08 --- # Fail2ban protection @@ -25,14 +25,29 @@ The file is written through a **staged step**: it is kept only if `fail2ban-clie configuration, otherwise the previous one is put back and the plan stops. Then the service is enabled and reloaded, and the plan waits for the socket. -**What a ban blocks.** `sshd` and `recidive` bans block every port from the address. The web jails and the Odoo -jail block **only the web ports**, through ufw's `Nginx Full` application profile (installed with the nginx -package), so a mistyped Odoo password from your office never locks you out of SSH. Without that profile, -fail2ban's ufw action blocks every port. List your admin networks in the ignore list anyway. - -> **UFW prerequisite:** the ban action is `ufw`, so bans only take effect if **UFW is installed and active**. -> The tool does not install UFW — set it up separately (`apt-get install ufw && ufw enable`) or the jails will -> run but never actually block traffic. +**What a ban blocks.** + +```mermaid +flowchart LR + ssh["sshd · recidive"] --> all(["all ports
of that address"]) + web["nginx-http-auth · nginx-botsearch
odoo-auth (per instance)"] --> webports(["web ports only
ufw profile Nginx Full"]) + ignore[("ignore list
loopback + your admin networks")] -.-> never["never banned"] + classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a + classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d + classDef stop fill:#fee2e2,stroke:#dc2626,color:#7f1d1d + classDef data fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class ssh,web step + class all,webports stop + class never guard + class ignore data +``` + +A failed Odoo or web login therefore never blocks SSH. The `Nginx Full` profile comes with the nginx package; +without it, fail2ban's ufw action blocks every port. + +> **UFW prerequisite:** the ban action is `ufw`, so bans only take effect while **UFW is installed and +> active**. This menu does not install UFW: set it up from **Firewall (UFW)**, which allows SSH before enabling +> it ([Firewall](firewall.md)). Until then the jails run but block nothing. ## Per-instance Odoo jail @@ -46,9 +61,8 @@ The filter matches Odoo's own login-failure line, which changed in Odoo 19: It is anchored on the `odoo.addons.base.models.res_users` logger, and only the request's performance numbers may follow the address. The plan **tests the filter** with `fail2ban-regex` on one line of each format and fails -unless both match. An empty production log would prove nothing: `fail2ban-regex` succeeds with zero matches. - -When you purge an instance, its jail is removed with its log. +unless both match (a test against the instance's own log could not tell: `fail2ban-regex` succeeds with zero +matches). ### Real-client-IP check (important behind a proxy) diff --git a/docs/server-audit.md b/docs/server-audit.md index bb2a233..0216415 100644 --- a/docs/server-audit.md +++ b/docs/server-audit.md @@ -4,7 +4,7 @@ title: "Auditing a server (external report)" description: "Generate a read-only report of a server's Odoo instances, TLS posture, and versions." tags: [audit, discovery, tls, reporting] audience: [operator] -updated: 2026-07-04 +updated: 2026-10-08 --- # Auditing a server (external report) @@ -30,9 +30,9 @@ server you are auditing or preparing to hand off. / none) and reports certificate metadata and expiry status (OK / WARN if expiring within the threshold / MISSING / ERROR). - **Odoo version** — read from `/odoo/odoo/release.py` (`version_info`) when available. -- **Production posture** — a per-instance table that flags `list_db`, guessable default master/DB credentials, - wkhtmltopdf, worker sizing, remote `db_sslmode`, and `dbfilter`. Read-only, computed from each instance's - `odoo.conf` plus host facts (same evaluation as the **Status: security & production** view); no mutation. +- **Production posture** — a per-instance table of the checks listed under + [security & production posture](operations/instance-management.md#security--production-posture), computed + from each instance's `odoo.conf` plus host facts; read-only. Instance discovery also recognizes the legacy config path `/etc//odoo.conf` in addition to the default `/etc/odoo//.conf`.