Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
91 changes: 91 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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 <name> → /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 `[<version>] - <YYYY-MM-DD>` (leave a fresh empty `[Unreleased]` on top), bump `version`
in `pyproject.toml` to match, add the `[<version>]` compare/tag link at the bottom, then tag `v<version>`.
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
```
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
92 changes: 1 addition & 91 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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 <name> → /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 `[<version>] - <YYYY-MM-DD>` (leave a fresh empty `[Unreleased]` on top), bump `version`
in `pyproject.toml` to match, add the `[<version>]` compare/tag link at the bottom, then tag `v<version>`.
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
50 changes: 34 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand Down Expand Up @@ -52,33 +56,47 @@ 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<br/>(backup · health · logs · addons)"]
menu --> sec["Security<br/>(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<br/>Odoo 12–19 · PostgreSQL"]
menu --> manage["Manage instances<br/>status · backups · duplicate"]
menu --> services["Instance services<br/>start · stop · restart"]
menu --> sec["Fail2ban · Firewall"]
menu --> remove["Remove instances"]
menu --> report[("Server report<br/>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.

**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.
Expand All @@ -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
Expand Down
Loading
Loading