Data residency check

A Cluster ERP deployment can declare the country it serves. The command python -m cluster_erp.server.residency_check then looks for anything in the configuration or in the control plane that contradicts that declaration. This page explains the rule behind it, every finding code, and the limits of the check. The settings themselves are listed in the configuration reference.

In short¶

• The declaration is CLUSTER_ERP_NODE_COUNTRY, a two-letter ISO 3166-1 code; without it the command prints that no policy is declared and exits with code 0 (src/cluster_erp/server/residency_check.py:347-355, src/cluster_erp/config/settings.py:756-760).
• With a declaration the command prints a summary, then either CLEAN: nothing contradicts the declaration. with exit code 0 or the findings with exit code 1 (src/cluster_erp/server/residency_check.py:358-373).
• The checks are pure functions over settings and tenant rows; only collect reads the control plane (src/cluster_erp/server/residency_check.py:28-29, src/cluster_erp/server/residency_check.py:325-344).
• install.sh runs the check after every install and refuses to report the release as live when it fails (deploy/install.sh:258-259).

How it works¶

main builds Settings, calls collect, and prints the result (src/cluster_erp/server/residency_check.py:347-373). collect runs config_findings and, on a multi-tenant node, adds tenant_findings over the (key, region) pairs of every tenant whose registration is not deleted (src/cluster_erp/server/residency_check.py:325-344).

Finding codes¶

Nineteen codes, counted as the Finding(...) constructors in residency_check.py.

A path counts as absolute when it is absolute in either the POSIX or the Windows convention, and as remote when it starts with two slashes after backslashes are turned into slashes (src/cluster_erp/server/residency_check.py:55-72).

Why it is built this way¶

• The module states the policy: a customer's data stays in that customer's country, stored and processed there, so a deployment is one complete node per country (src/cluster_erp/server/residency_check.py:5-9).
• Code cannot verify geography, so the check reports only contradictions with the declaration (src/cluster_erp/server/residency_check.py:11-14).

Rules and boundaries¶

• Settings already refuses a country code that is not two letters, and a CLUSTER_ERP_COUNTRY_NODES map that omits the node's own country (src/cluster_erp/config/settings.py:756-767).
• The tests are in tests/test_residency_check.py; the browser suite is web-client/_e2e_residency.mjs.

Interaction with other parts¶

• The signup entry form and the operator console read node_country and country_nodes to send a customer to the node of their country (src/cluster_erp/server/routes/signup.py:126-138, src/cluster_erp/server/routes/vendor.py:157). See signup.
• The backup, storage, and archive settings it checks are described in backups and restore.

Limits and open points¶

• A drive letter mapped to a remote share reads as local; the module leaves that gap to the operator (src/cluster_erp/server/residency_check.py:25-26).
• The check does not resolve host names or look up where an address is located; REGION-DB-REMOTE asks the operator to confirm (src/cluster_erp/server/residency_check.py:205-212).

Terms introduced¶

Related pages¶

• Operations
• Install a Linux node
• Multi-tenancy
• Configuration reference

Verified against commit 92f8051 on 2026-11-13.