Module Architecture

flowchart TD
    BASE["sadeem_saas_base\nSAAS Base"]

    CON["sadeem.nginx.connector\nServer URL · JWT token\nauto token refresh"]
    HOST["sadeem.nginx.host\nDomain · forward host:port\nSSL cert ID · proxy state"]
    EXT[/Nginx Proxy Manager API\nJWT-authenticated REST/]

    BASE --> CON
    CON --> HOST

    CON --> A1([action_confirm\ngenerate JWT token → active])
    CON --> A2([action_reset_draft\nreset to draft])
    CON --> A3([action_cancel\ndeactivate server])
    CON --> A4([check_token_validity\nrefresh JWT if near expiry])
    CON --> A5([action_open_nginx_panel\nopen NPM web UI in browser])

    HOST --> A6([nginx_manager_host_action\ncreate host + provision SSL cert])
    HOST --> A7([action_start\nenable proxy host])
    HOST --> A8([action_stop\ndisable proxy host])
    HOST --> A9([action_delete\ndelete host + unlink record])
    HOST --> A10([action_check_status\nGET live state → post chatter])
    HOST --> A11([ssl_certificate_action\nreuse latest valid cert or create new])

    A1 --> EXT
    A6 --> EXT
    A7 --> EXT
    A8 --> EXT
    A9 --> EXT
    A10 --> EXT

Module Description

Integrates Odoo with the Nginx Proxy Manager API for reverse proxy and SSL management.

Area	What it does
Servers	Connect to NPM instances with JWT auth and automatic token refresh
Proxy Hosts	Create, enable, disable, and delete proxy hosts remotely
SSL Certificates	Auto-provision Let's Encrypt certs on host creation; reuses latest valid cert if found
Status Checks	Verify live host state and compare against local config
Lifecycle	Draft → Running → Stopped / Redirect / Deleted with chatter tracking

Dependencies

mail
sadeem_saas_base

Menus

SAAS Management
├─ Infrastructure
⎢   └─ Nginx Proxy Manager
⎢       └─ Servers
└─ Data
    └─ Nginx Proxy Hosts

Key Fields

Nginx Connector (sadeem.nginx.connector)

Field	Type	Description
url	Char	NPM API base URL (e.g., `https://npm.example.com`) (required)
ip	Char	IP address of the NPM server (required)
username	Char	NPM login username (required)
password	Char	NPM login password (required)
token	Char	JWT token (auto-generated, read-only)
token_expiry	Datetime	When the JWT token expires (read-only)
state	Selection	Connector status: `draft`, `confirm`, `cancel`

Nginx Host (sadeem.nginx.host)

Field	Type	Description
name	Char	Domain name for the proxy host (required)
nginx_server	Many2one	The NPM connector to use (required; must be in `confirm` state)
nginx_id	Integer	NPM's internal proxy host ID (set after creation)
certificate_id	Integer	NPM's SSL certificate ID (set after provisioning)
redirected_to	Char	Redirect target URL (used when state is `redirect`)
state	Selection	Host lifecycle: `draft`, `run`, `redirect`, `stop`, `delete`
created_on_remote	Boolean	Whether the host has been created on NPM

Lifecycle & States

Connector States

State	Meaning
`draft`	Not yet authenticated
`confirm`	JWT token obtained, connector is active
`cancel`	Connector deactivated

Transitions: - draft → confirm: action_confirm — POSTs credentials to NPM API to obtain JWT token - confirm → draft: action_reset_draft - Any → cancel: action_cancel - Token auto-refresh: check_token_validity checks expiry before each API call and re-authenticates if needed

Proxy Host States

State	Meaning
`draft`	Host defined locally, not yet created on NPM
`run`	Host active and proxying traffic
`redirect`	Host configured as a redirect (not a proxy)
`stop`	Host disabled on NPM
`delete`	Host deleted from NPM

Transitions: - draft → run / redirect: nginx_manager_host_action — creates proxy host on NPM and provisions SSL cert - run / redirect → stop: action_stop — disables the host on NPM - stop → run / redirect: action_start — re-enables the host - Any → delete: action_delete — deletes the host from NPM

Key Actions

Action	Model	Description
`action_confirm`	sadeem.nginx.connector	Authenticates with NPM and stores JWT token
`action_reset_draft`	sadeem.nginx.connector	Resets connector to draft state
`action_cancel`	sadeem.nginx.connector	Cancels the connector
`action_open_nginx_panel`	sadeem.nginx.connector	Returns URL action to open the NPM web UI
`check_token_validity`	sadeem.nginx.connector	Refreshes JWT if expired or near expiry
`nginx_manager_host_action`	sadeem.nginx.host	Creates or updates proxy host on NPM; provisions SSL cert via `ssl_certificate_action`
`action_start`	sadeem.nginx.host	Re-enables a stopped proxy host
`action_stop`	sadeem.nginx.host	Disables a running proxy host
`action_delete`	sadeem.nginx.host	Deletes the proxy host from NPM and marks local record as `delete`
`action_check_status`	sadeem.nginx.host	Fetches live host state from NPM and posts a chatter comparison message

Warnings & Important Notes

Connector deletion blocked: Cannot delete a sadeem.nginx.connector that has associated proxy hosts — raises UserError.
Token generation failure: action_confirm raises UserError with NPM's error message if authentication fails.
Host requires confirmed connector: nginx_server field has domain filter [("state", "=", "confirm")]; cannot use an unconfirmed connector.
Unlink guard on hosts: unlink raises UserError if the host created_on_remote is True and state is not delete — must call action_delete first.
SSL auto-provisioning: On host creation, ssl_certificate_action first searches for a valid existing Let's Encrypt cert for the domain; only creates a new one if none is found.
Forward defaults: The module uses internal Docker gateway IP 172.17.0.1 as default forward host, with configurable ports per host.