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 new file mode 100644 index 0000000..1a7e427 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# 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 +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, 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 + `[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/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/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/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`. 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)