Service and process manager

This page describes how a Linux node runs the Cluster ERP server: the systemd unit deploy/cluster-erp.service, the gunicorn configuration deploy/gunicorn.conf.py, and the two entry points src/cluster_erp/server/asgi.py and src/cluster_erp/server/main.py. It ends with the boot sequence of one worker. What the application does inside its start-up is explained in server startup and app factory.

Scope and source¶

• Defined in: deploy/cluster-erp.service, deploy/gunicorn.conf.py, src/cluster_erp/server/asgi.py (app), src/cluster_erp/server/main.py (main).
• Count: the unit table lists every directive of the [Unit], [Service], and [Install] sections; the gunicorn table lists every module-level setting of the configuration file.

Paths of a real node are written as the unit's own names (WorkingDirectory, EnvironmentFile, ReadWritePaths) and not as values.

Entry points¶

main.py passes the proxy settings to uvicorn: proxy_headers from trust_proxy_headers, forwarded_allow_ips from trusted_proxy_ips, the access log switch, and the keep-alive seconds (src/cluster_erp/server/main.py:39-58).

Systemd unit¶

Gunicorn configuration¶

Every value comes from the same environment file the application reads (deploy/gunicorn.conf.py:11-13, deploy/gunicorn.conf.py:22-23).

Boot sequence¶

The diagram shows what happens from systemctl start until a worker is ready. Each worker runs the whole sequence; the migration lock makes the workers take turns on the schema step.

flowchart TD
  systemd["systemd cluster-erp.service"] --> master["gunicorn master"]
  master --> w1["worker 1 imports asgi:app"]
  master --> w2["worker N imports asgi:app"]
  w1 --> life["lifespan start"]
  w2 --> life
  life --> mt{"multi_tenant"}
  mt -- "yes" --> lock["upgrade_database_to_head under migration_lock"]
  lock --> ctl["TenantRegistry.ensure_schema and bootstrap operator"]
  mt -- "no" --> budget["connection budget check"]
  ctl --> budget
  budget --> load["registry.load_all and seeds"]
  load --> loops["background loops started"]
  loops --> ready["GET /ready answers 200"]

In prose:

1. systemd starts the gunicorn master with the configuration file (deploy/cluster-erp.service:25).
2. The master starts the workers; each imports cluster_erp.server.asgi:app, which calls create_app() (src/cluster_erp/server/asgi.py:17-19).
3. The lifespan context of each worker starts (src/cluster_erp/server/app.py:58-65).
4. In multi-tenant mode the worker creates the default database if needed and migrates it to the newest revision inside the advisory migration lock; a second worker waits and then finds nothing to do (src/cluster_erp/server/app.py:99-113, src/cluster_erp/core/tenancy.py:693-720). It then prepares the control plane and the first operator (src/cluster_erp/server/app.py:114-118). A single-tenant worker does not migrate.
5. The worker compares the worst-case connection demand with the server's max_connections and logs a POOL BUDGET warning when it does not fit (src/cluster_erp/server/app.py:119-128, src/cluster_erp/server/app.py:610-631).
6. The worker loads every enabled module, seeds sequences and permissions, replays the erasure ledger, and starts the background loops (src/cluster_erp/server/app.py:139-194).
7. The context yields; /ready probes the database and, in multi-tenant mode, the control plane (src/cluster_erp/server/app.py:196, src/cluster_erp/server/app.py:1476-1504).

Reload and restart¶

• systemctl reload sends HUP; new workers import the current code because the application is not preloaded (deploy/gunicorn.conf.py:3-10, deploy/gunicorn.conf.py:32-34).
• install.sh restarts instead of reloading when the environment file is newer than the running service, when the unit changed, or when requirements.lock changed. A reloaded worker inherits the packages the master already imported (deploy/install.sh:140-144, deploy/install.sh:228-246).

Constraints and validation¶

• On Windows main.py ignores server_workers above one and logs a warning (src/cluster_erp/server/main.py:27-35).
• Reload and worker processes exclude each other in main.py (src/cluster_erp/server/main.py:36-38).

Discrepancies¶

Terms introduced¶

Related pages¶

• Operations
• Server startup and app factory
• Database migrations
• Reverse proxy

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