OpenCore MES Try the demo

Docs Installation 7

Reference

On this page

7.1 Settings

SettingDefaultWhat
PROD=1offProduction: no sign-in picker, Secure cookies, a snapshot of the pages.
HOST, PORT0.0.0.0, 9090Where it listens: 127.0.0.1 behind Caddy.
DATABASE_URL, PGHOSTdevelopment's own: always set itThe database (a plant's: postgres:///opencore_mes); PGHOST the socket's folder.
PLANT_TZthe server'sThe time zone of schedules that name none.
EVENT_LOG_DIR.local/eventsWhere the event log file is written.
TRUST_PROXYunsetHow many proxies are in front (1 behind Caddy), so the client's address is the real one.
SEAL_KEY_FILE, INTEGRITY_KEY_FILEnone: required with PROD=1The 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_HOURS168How 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=0onNo passwords of OpenCore MES's own.
MFAoptionalrequired or off: an authenticator's code after a password.
SIGN_WITH_PASSWORD=0onSignatures ask the signer's password (or a fresh single sign-on).
PASSWORD_MAX_DAYS, PASSWORD_HISTORY90, 5Password expiry and reuse.
SESSION_IDLE_MINUTES30Sign-out after that long with nothing done (12 hours at most).
PASSWORD_LINK_DAYS3How long a one-time password link lasts unless its maker says (1 to 14 days).
SIGN_IN_LIMIT30/10Wrong 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=requirednoneThe script runner's walls (IN-16).
MES_CONNECTION_HOSTSany hostThe 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_SEVERITYnone, errorAlerts (IN-19).
SETUP=1offSetup 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_MODELnoneThe copilot.
SUITES_DIR, SUITES_REGISTRYsuites/, the store'sWhere suites are, and where they come from.
COPILOT_DIRcopilot/Where the copilot's versions are installed, beside the one shipped with the core (IN-53).
SHUTDOWN_GRACE_MS60000How 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

PathWhat
/srv/opencore-mes/releases/<build>Each release; /srv/opencore-mes/current points at the one that runs.
/etc/opencore-mes/opencore-mes.envThe settings (root:opencore, 0640).
/etc/opencore-mes/seal.key, integrity.key, backup.keyThe keys (copies off the server).
/etc/opencore-mes/backup.envWhat is backed up, where, and where it is copied.
/var/lib/opencore-mes/eventsThe event log file (also copied into the database).
/var/lib/opencore-mes/copilotThe copilot's versions installed beside the one shipped (COPILOT_DIR; IN-53).
/var/backups/opencore-mesThe 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 --emptyAn empty database. Everything in the database is lost; refused on a protected one.
db/admin.mjs <id> "<name>" · opencore-mes adminThe first administrator of an empty installation.
db/password.mjs <id> --url <site> · opencore-mes passwordA one-time link for a person to set their password.
db/token.mjs <user> "<name>" [--days 1..365] [--test] · opencore-mes tokenA 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 migrateThe 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.mjsSecond-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.
The Database area: this server, restart and stop, errors, and the calls asked of the database
The Database area, for database administrators: this server, its errors, and what is asked of the database.
The Database area: this server, restart and stop, errors, and the calls asked of the databaseThe Database area, for database administrators: this server, its errors, and what is asked of the database.

7.4 When something refuses

You seeWhy, 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 addressMany 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 wallsSCRIPT_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 yetThe database is empty: name the first administrator (IN-15).
npm install -g: EACCES, permission denied on /usr/local/lib/node_modulesnpm'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 peopleThe 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 … alreadyThe 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 resetIts audit trail is protected (IN-17): it is a plant's. Restore a backup into a new database instead (IN-42).
/healthz answers 503The 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 refusedA 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 stopSomething 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 databaseIt changes the audit trail: run it as postgres, then protect-audit.sql (IN-17).
SETUP=1 ignoredChanges were already reviewed and approved there: setup is opened again by a change governance approves.
Data retention: how long each kind of data is kept and what is past it
Data retention: how long each kind of data is kept, what is past it, and a person's data erased.
Data retention: how long each kind of data is kept and what is past itData retention: how long each kind of data is kept, what is past it, and a person's data erased.

7.5 Revision history

RevisionDateWhat changed
A2026-10-06First issue.
B2026-10-06Laptops: a MacBook and a Windows laptop (WSL 2), the sample plant or a plant of one's own (IN-31 to IN-33).
C2026-10-07MacBook: npm's global folder of one's own (EACCES with the nodejs.org installer); two more refusals explained.
D2026-10-07IN-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.
E2026-10-10IN-33: a source archive has five dependencies.
F2026-10-10A 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.
G2026-10-10A language for the floor: a language pack installed, the language offered, the designs translated (IN-52).
H2026-10-11The 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.
I2026-10-11A 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).
J2026-10-17Changes 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).