Docs Installation 7
Reference
On this page
7.1 Settings
| Setting | Default | What |
|---|---|---|
PROD=1 | off | Production: no sign-in picker, Secure cookies, a snapshot of the pages. |
HOST, PORT | 0.0.0.0, 9090 | Where it listens: 127.0.0.1 behind Caddy. |
DATABASE_URL, PGHOST | development's own: always set it | The database (a plant's: postgres:///opencore_mes); PGHOST the socket's folder. |
PLANT_TZ | the server's | The time zone of schedules that name none. |
EVENT_LOG_DIR | .local/events | Where the event log file is written. |
TRUST_PROXY | unset | How many proxies are in front (1 behind Caddy), so the client's address is the real one. |
SEAL_KEY_FILE, INTEGRITY_KEY_FILE | none: required with PROD=1 | The two keys (IN-13), or SEAL_KEY, INTEGRITY_KEY themselves: 64 hex characters each, not the same. A production server does not start without them. |
INTEGRITY_FULL_HOURS | 168 | How often the integrity scan reads every record. |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_CLAIM, OIDC_LABEL | — | Single sign-on. The redirect address is https://<server>/login/sso/callback; the claim is the sign-in id (preferred_username unless set). |
LDAP_URL, LDAP_USER_DN, LDAP_CA_FILE, LDAP_LABEL | — | The directory: ldaps://host:636, and whom an id binds as ({user}@plant.local). |
PASSWORDS=0 | on | No passwords of OpenCore MES's own. |
MFA | optional | required or off: an authenticator's code after a password. |
SIGN_WITH_PASSWORD=0 | on | Signatures ask the signer's password (or a fresh single sign-on). |
PASSWORD_MAX_DAYS, PASSWORD_HISTORY | 90, 5 | Password expiry and reuse. |
SESSION_IDLE_MINUTES | 30 | Sign-out after that long with nothing done (12 hours at most). |
PASSWORD_LINK_DAYS | 3 | How long a one-time password link lasts unless its maker says (1 to 14 days). |
SIGN_IN_LIMIT | 30/10 | Wrong sign-in tries (a password, a code, a setup code) from one address in so many minutes, after which every sign-in from it is refused until the oldest is that old; 0 for none. Each server counts its own, by the address TRUST_PROXY reads. |
SCRIPT_RUNNER_WRAP, SCRIPT_ISOLATION=required | none | The script runner's walls (IN-16). |
MES_CONNECTION_HOSTS | any host | The hosts services may reach (comma separated). Never a link-local or unspecified address (a cloud's metadata service), listed or not. |
ALERT_WEBHOOK_URL, ALERT_MIN_SEVERITY | none, error | Alerts (IN-19). |
SETUP=1 | off | Setup at the first start of an installation not made empty (the first administrator of an empty one opens it already). |
REPLICA_URL, BUS=1, INSTANCE | — | Reads from a replica; several instances on one database (app/mes/README.md, Scaling): then ops/db/settings.sh --servers <instances> again (IN-15). |
AI_PROVIDER, ANTHROPIC_API_KEY, AI_MODEL | none | The copilot. |
SUITES_DIR, SUITES_REGISTRY | suites/, the store's | Where suites are, and where they come from. |
COPILOT_DIR | copilot/ | Where the copilot's versions are installed, beside the one shipped with the core (IN-53). |
SHUTDOWN_GRACE_MS | 60000 | How long a stop waits for what is under way (saves, transactions, copilot answers) before it cuts it. The unit's TimeoutStopSec must be longer. |
The full list, with every option: the header of app/mes/server.mjs and app/mes/README.md.
7.2 Files and folders
| Path | What |
|---|---|
| /srv/opencore-mes/releases/<build> | Each release; /srv/opencore-mes/current points at the one that runs. |
| /etc/opencore-mes/opencore-mes.env | The settings (root:opencore, 0640). |
| /etc/opencore-mes/seal.key, integrity.key, backup.key | The keys (copies off the server). |
| /etc/opencore-mes/backup.env | What is backed up, where, and where it is copied. |
| /var/lib/opencore-mes/events | The event log file (also copied into the database). |
| /var/lib/opencore-mes/copilot | The copilot's versions installed beside the one shipped (COPILOT_DIR; IN-53). |
| /var/backups/opencore-mes | The encrypted backups (postgres, 0700). |
| /etc/systemd/system/opencore-mes.service; opencore-mes-backup.*; opencore-mes-restore-test.* | The service and the backup timers. |
7.3 Console commands
Command (on a server: node app/mes/… with the settings loaded) | What |
|---|---|
db/reset.mjs --empty · opencore-mes db reset --yes --empty | An empty database. Everything in the database is lost; refused on a protected one. |
db/admin.mjs <id> "<name>" · opencore-mes admin | The first administrator of an empty installation. |
db/password.mjs <id> --url <site> · opencore-mes password | A one-time link for a person to set their password. |
db/token.mjs <user> "<name>" [--days 1..365] [--test] · opencore-mes token | A token for an integration user; --test: one for the test sandbox's web services alone (its own port, this server's + 1000), never the live ones. |
db/migrate.mjs · opencore-mes db migrate | The database brought up to date (the server does it at start). |
db/verify-audit.mjs [--full] | The audit chain checked by hand. |
db/seal-secrets.mjs | Second-factor secrets kept before a seal key was set, sealed now. |
db/recover-designer.mjs <designer> [--reviewer <user>] "<why>" | Design roles given back when nobody can change the system any more; refused otherwise, audited. |


7.4 When something refuses
| You see | Why, and what to do |
|---|---|
The service stops at start: Not starting: PROD=1 and no SEAL_KEY … (or INTEGRITY_KEY, or the same key twice, or a key file it cannot read) | Production needs its two keys: make them and name them in the settings (IN-13). The message names what is missing. |
| Signing in says too many wrong sign-in attempts from this address | Many wrong passwords or codes came from that address in the last minutes (SIGN_IN_LIMIT): wait the minutes it says. Behind Caddy without TRUST_PROXY=1 every person comes from the proxy's address: set it (IN-13). |
| The service stops at start: the script runner has no walls | SCRIPT_ISOLATION=required without bubblewrap or its AppArmor profile: install them (IN-16), or remove the setting while you do. |
| Signing in says nobody has been added yet | The database is empty: name the first administrator (IN-15). |
npm install -g: EACCES, permission denied on /usr/local/lib/node_modules | npm's global folder belongs to root (Node from the nodejs.org installer on a Mac, or Ubuntu's packages): give npm one of your own (IN-31 step 2, IN-32 step 5), not sudo. |
opencore-mes: unknown command admin, or --empty loads the sample people | The npm package is 0.1.0, from before them: try the sample plant with it, or install from a source archive (IN-33) until the next package. |
admin.mjs: People & departments has … already | The first administrator is named once; add people through a change, or recover with recover-designer.mjs if nobody can change the system. |
reset.mjs: a protected database is never reset | Its audit trail is protected (IN-17): it is a plant's. Restore a backup into a new database instead (IN-42). |
/healthz answers 503 | The database is not answering, or the service is stopping: journalctl -u opencore-mes. |
The journal says Nobody active is a sign-in administrator (or database administrator) | Nobody can lift a lockout or give a password link (or read the errors and restart a server). A designer names one in People & departments (Roles → Sign-in, Roles → Database) through a change; until then any change to People & departments is refused for that reason. |
| Pages say the server is restarting, and saving is refused | A stop is draining: nothing new is saved while what was under way finishes, at most SHUTDOWN_GRACE_MS. A restart is back within seconds; after a Stop from the Database area (exit 64) the service stays stopped: systemctl start opencore-mes. |
Someone reads Something went wrong on the server (error E-…) | The server met an error nothing meant to refuse, and kept it: open the Database area, Errors, and type the reference they give you; the line shows each time it happened, who met it, and the server's stack. If it comes from the database (a timeout, a lock), the journal and /healthz say more. |
The journal says cut: after a stop | Something was still running when the grace was up, and was cut (named there and in the event log, instance.cut). If it happens at every deploy, raise SHUTDOWN_GRACE_MS and TimeoutStopSec with it. |
| A migration fails at start on a protected database | It changes the audit trail: run it as postgres, then protect-audit.sql (IN-17). |
SETUP=1 ignored | Changes were already reviewed and approved there: setup is opened again by a change governance approves. |


7.5 Revision history
| Revision | Date | What changed |
|---|---|---|
| A | 2026-10-06 | First issue. |
| B | 2026-10-06 | Laptops: a MacBook and a Windows laptop (WSL 2), the sample plant or a plant of one's own (IN-31 to IN-33). |
| C | 2026-10-07 | MacBook: npm's global folder of one's own (EACCES with the nodejs.org installer); two more refusals explained. |
| D | 2026-10-07 | IN-20: everyone's first password with setup codes (a file for printed slips), and moving to the plant's directory; the sign-in id's label, hint and domains. |
| E | 2026-10-10 | IN-33: a source archive has five dependencies. |
| F | 2026-10-10 | A production server does not start without its two keys (IN-13; IN-33 way B makes them on a laptop); SIGN_IN_LIMIT, wrong sign-in tries per address; MES_CONNECTION_HOSTS never reaches a link-local address; IN-18 adds WAL archiving with point-in-time recovery and copies off the host. |
| G | 2026-10-10 | A language for the floor: a language pack installed, the language offered, the designs translated (IN-52). |
| H | 2026-10-11 | The copilot upgraded without a restart: installed beside the others, chosen, taken up by every server, an old one removed (IN-53); a server whose chosen version cannot run runs the shipped one, saying so. |
| I | 2026-10-11 | A graceful stop: the unit's KillMode=mixed, TimeoutStopSec=90 and RestartPreventExitStatus=64 (IN-14); SHUTDOWN_GRACE_MS; restarting and stopping from the Database area; four refusals explained; the platform's unexpected errors kept, each with a reference (Database area, Errors); never without a sign-in and a database administrator, the first administrator both (IN-15). |
| J | 2026-10-17 | Changes executed by hand, then verified: the first administrator is an executor too (IN-15), a setup change verified (IN-20), how changes go live decided (IN-20, IN-21), and what the first upgrade to it changes (IN-40). |