OpenCore MES Try the demo

Docs Integration 2

Installing OpenCore MES

On this page

OpenCore MES is plain JavaScript on Node and PostgreSQL: no build step, two runtime packages (pg, and the Anthropic SDK for the copilot). One Node process is one instance; instances share one database.

About OpenCore MES: version, build, Juris and Node.js, and the suites installed
About OpenCore MES: the version, build and runtime this installation runs, and its suites.
About OpenCore MES: version, build, Juris and Node.js, and the suites installedAbout OpenCore MES: the version, build and runtime this installation runs, and its suites.
Caution. In development (and on a public demo, DEMO=1, reset every night) sign-in is a picker: a person picks who they are, so anyone who can reach that instance can act as anyone. Keep development on HOST=127.0.0.1 or a network you trust. With PROD=1 the picker is off and people sign in as 2.3 describes.

2.1 What you need

WhatVersionWhy
Node24 or laterthe server, the script runner, the tools
PostgreSQL16 or later (the pipeline runs on 16)everything that is kept: designs, records, audit, outbox, sessions
Google Chrome or Chromiumany recentonly to build the printable guides (--pdf)
IN-01Install from npm
PurposeA running instance from the published package, with nothing to check out: to try OpenCore MES, or to run it as a plant's.
Done byIT or a developer
Before you start
  • Node 24 and PostgreSQL are installed; your user can create databases over the local socket (or DATABASE_URL names one it may).
#Do thisYou should seeDone
1Install the package.
npm install -g @opencore-mes/server
The opencore-mes command. The package holds the code only, and nothing writes to it.
2Make a plant folder, and go into it.
opencore-mes init my-plant
cd my-plant
A plant folder: .env (its settings, commented: the database, the port, sign-in, the copilot), suites/, .local/ (the event log). An existing .env is left as it is.
3Set the database in .env (DATABASE_URL, by default postgres:///opencore_mes), then make it, with the sample plant to try it:
opencore-mes db reset --yes
Cannot be undone. It makes the database named in .env again: everything in it is lost.
The database is made, its schema loaded and the seed loaded (sample people, to try it). Without --yes it refuses: a reset loses everything in the database.
4For the plant's own installation instead, an empty database and its first administrator (replace what is between < >):
opencore-mes db reset --yes --empty
opencore-mes admin <id> "<Full name>" --url https://<this site>
Cannot be undone. The first line makes the database again (everything in it is lost); the second runs once per installation: check the id and name first.
Nobody is in it but that first administrator: designer, reviewer and executor, sign-in and database administrator, approver for the department that governs. A one-time link to set their password is printed (--no-password when they sign in through SSO or the directory). Setup is open: they add the plant's people and end setup. Refused once anybody is in People & departments.
5Start it, from inside the plant folder.
opencore-mes start
“listening on http://127.0.0.1:9090”, with the folder's .env, suites and event log.
6Open it and pick a person to sign in as.The navigator, the designer, the screens. For production, set PROD=1 and a way to sign in (2.2, 2.3).
opencore-mes db migrate migrates without starting; opencore-mes token <user> "<name>" and opencore-mes password <user> --url <site> are the token and password tools of 2.3 and the tutorial. To upgrade, npm install -g @opencore-mes/server@latest and restart: the server migrates at start. Suites go in the plant folder's suites/: opencore-mes suite install <name> from the suites registry, with the plant's licence token (opencore-mes suite login; the suites store at suites.opencoremes.com is not open yet), or --from <file>.tgz for a plant with no way out; every version a plant ran is kept in suites/.versions/ (suite list, suite use <name>@<version>). The contracts are packages too, with their kits: @opencore-mes/equipment-adapter and @opencore-mes/http-apis.
IN-02Install for development
PurposeA working instance on your machine, with the seed's plant to try things on.
Done byDeveloper
Before you start
  • Node 24 and PostgreSQL are installed; your user can create databases over the local socket.
#Do thisYou should seeDone
1Get the code, and install its dependencies.
git clone https://github.com/opencore-mes/opencore-mes.git
cd opencore-mes
npm install
Its packages installed.
2Make the development database.
npm run db:reset
Cannot be undone. It makes the development database opencore_mes_poc again: everything in it is lost. For tests, name the test database instead: DATABASE_URL=postgres:///opencore_mes_test.
The database opencore_mes_poc is made (when missing), its schema loaded and migrated, and the seed loaded: people, departments, objects, records. It says what it loaded.
3Optionally, copy .env.example to .env and set what you need (the copilot's provider, a port)..env is never committed.
4Start it; it restarts by itself on a change.
npm run dev
“listening on http://127.0.0.1:9090”. It restarts when a file under app/mes changes, and every open page reloads (the framework, in node_modules, is not watched: restart it after npm install).
5Open it and pick a person to sign in as (Dana designs; Olga works the floor).The navigator, the designer, the screens.
6Run the whole test pipeline.
npm run test:all
Every stage passes. It resets opencore_mes_test (TEST_DATABASE_URL) and refuses any database whose name lacks “test”, so your development database is safe.
DATABASE_URL names another database; npm run db:reset -- --blank makes one with people only (every model designed from nothing), as the training instance does (npm run training:reset, npm run training, port 9091).
IN-03Install on a server
PurposeOne instance behind HTTPS, run by systemd, as the public demo is (ops/demo).
Done byIT
Before you start
  • A fresh Ubuntu 24.04 server, root access, a DNS name pointing at it.
#Do thisYou should seeDone
1As root, run ops/demo/provision.sh (safe to run again).PostgreSQL, Caddy, Node (its checksum checked); the system user opencore; its database role over the local socket (peer authentication, no password); the role mes_query the query page reads as, granted to opencore.
2Unpack a release in /srv/opencore-mes/releases/<build>, owned by opencore, and install its dependencies there:
cd /srv/opencore-mes/releases/<build>
sudo -u opencore npm ci --omit=dev
—
3Write its settings in an environment file (as ops/demo/demo.env): PROD=1, HOST=127.0.0.1, PORT=3000, DATABASE_URL=postgres:///opencore_mes, PGHOST=/var/run/postgresql, PLANT_TZ, EVENT_LOG_DIR=/var/lib/opencore-mes/events, and the two keys it does not start without, SEAL_KEY_FILE=/etc/opencore-mes/seal.key and INTEGRITY_KEY_FILE=/etc/opencore-mes/integrity.key (each 64 hex characters, made once as 2.2 says, root:opencore 0440). Secrets (the copilot's key, MES_SECRET_…) go in a file of their own under /etc/opencore-mes, mode 0640, root:opencore.No secret is in the release or its settings file.
4The first time only, as opencore with those settings loaded: an empty database and its first administrator (without --empty: the sample people and plant, to try it; --blank: the sample people only). The installation procedure (OMES-INS-001, IN-15) gives every step.
node app/mes/db/reset.mjs --empty
node app/mes/db/admin.mjs <id> "<Full name>" --url https://<name>
Cannot be undone. The first line makes the database again (everything in it is lost: a new installation only); the second runs once per installation: check the id and name first.
An empty database and its first administrator, with a one-time link to set their password; setup is open for them. Later releases migrate it at start.
5Only when the plant's engineers will set up an installation that was not made empty (the sample people) before anyone reviews their work: add SETUP=1 to the environment file before the first start (the first administrator of an empty one opens setup already).At start the event log says setup.opened; the designer shows Setup is open. Each designer's change then executes on their signature, until People & departments ends setup. Write in the handover that it was opened.
6Point /srv/opencore-mes/current at the release; install the systemd unit (as ops/demo/opencore-mes.service: ExecStart=/usr/local/bin/node app/mes/server.mjs, the environment files, ProtectSystem=strict, ReadWritePaths=/var/lib/opencore-mes), and start it:
systemctl enable --now opencore-mes
systemctl status opencore-mes shows it running.
7Put Caddy in front (as ops/demo/Caddyfile: your name, reverse_proxy 127.0.0.1:3000, HSTS), and reload it.Caddy fetches the certificate by itself.
8Ask it how it is, then open https://<name>/.
curl -fsS http://127.0.0.1:3000/healthz
The health answer; the sign-in page over HTTPS.
For a plant's own server, with its keys, the first administrator, backups, hardening and the checks before go-live, follow the installation procedure (OMES-INS-001, docs/installation/). ops/demo/deploy.sh does all of this from a workstation for the public demo (--provision the first time), runs the test pipeline on the server before switching, and keeps the last five releases. It is the demo's: it also installs the timer that erases the demo's database every night, and the landing page. Take the steps from it for a plant, not the script as it is.
IN-04Upgrade to a new release
PurposeA new version of OpenCore MES, with its database changes.
Done byIT
#Do thisYou should seeDone
1Unpack the release beside the current one, and install its dependencies there:
cd /srv/opencore-mes/releases/<new build>
sudo -u opencore npm ci --omit=dev
—
2Optionally run the pipeline there against a test database: TEST_DATABASE_URL=postgres:///opencore_mes_test npm run test:all.Every stage passes.
3Point current at it and restart the service.At start the server runs every new or changed migration, in order, under one lock: several instances starting together run each once. Nothing is run by hand.
4/healthz, and the event log.db.migrated names what ran.
5The first upgrade to a release with the data integrity review: an integrity reviewer (People & departments, Roles, Data integrity) opens Design → Data integrity and signs Take the baseline.What was there is sealed as it stands; from then on a change made around the platform is found. Changes written by hand are kept by the database from the upgrade on.
Designs are never part of a release: they live in the database and change only through change requests, so an upgrade leaves the plant's designs as they were. npm run db:migrate migrates without starting a server.

2.2 Settings

SettingWhat
DATABASE_URLthe database (default postgres:///opencore_mes_poc, the local socket)
PORT, HOSTwhere it listens (9090; every IPv4 address, :: for IPv6 too, 127.0.0.1 for this machine only)
PROD=1, BUILDproduction: a snapshot of the pages, minified, Secure cookies; this release's name. It does not start without its two keys, SEAL_KEY and INTEGRITY_KEY (below)
SEAL_KEY, SEAL_KEY_FILEthe key the authenticators' secrets are sealed under (AES-256-GCM): 64 hex characters (openssl rand -hex 32), not the integrity key, kept outside the database and its backups. Required with PROD=1: the server says what to set and stops
DEMO=1, DEMO_ASa public demo: no sign-in page, a visitor is the demo person (DEMO_AS, or the first who designs) and becomes anyone from the top bar; every page says so; services call no outside system
REPLICA_URLa streaming replica for reads, behind the replay fence (2.4)
BUS=1, INSTANCEjoin the change bus, to run several instances on one database; this instance's name
SESSION_COOKIEthe sign-in cookie's name, for a second instance on the same machine
SIMPLE_LISTS=1lists of people show everyone at once, as in development and on the demo (a test instance); otherwise they start with a search box
OIDC_ISSUER, LDAP_URL, PASSWORDS=0, PICKER=1how people sign in (2.3)
AI_PROVIDER …the copilot: anthropic (Claude: ANTHROPIC_API_KEY, AI_MODEL, AI_EFFORT) or openai (any OpenAI-compatible model: AI_BASE_URL, AI_API_KEY, AI_MODEL); unset, no copilot
MES_SECRET_<NAME>a connection's secret (5.9)
SETUP=1a new installation being set up by its engineers: at its first start, a designer's change executes on their signature, without review or approval, until People & departments ends setup (once someone besides the designers can review); every such change is marked and audited. Ignored, and said in the event log, where a change was already reviewed and approved; left set after setup ends, it changes nothing
INTEGRITY_KEY, INTEGRITY_FULL_HOURSthe data integrity review: 64 hex characters (openssl rand -hex 32, or INTEGRITY_KEY_FILE), kept with the environment, never in the database or its backups; every record is sealed under it, and a record, design, person or role changed straight in the database is found and reported to the plant's integrity reviewers (Design → Data integrity). Required with PROD=1; in development and the tests, without it the seals are plain digests. Set it before the first start; changed later, a reviewer seals everything again, signed. How often every record is read (168 hours; what was written, every 15 minutes)
SCRIPT_RUNNER_WRAP, SCRIPT_ISOLATION=requiredthe script runner's operating-system walls (ops/script-runner-sandbox.sh, Linux), and refusing to start without them (5.9)
OUTBOX=0, SCHEDULER=0, NODE_TAGS, PLANT_TZwhat this node runs for integration (5.11)
EVENT_LOG_DIRwhere the event log is written (default .local/events)
SEED_BLANK=1, SEED_EMPTY=1for db/reset.mjs: the sample people only; nobody at all (a plant's own installation, entered by the first administrator)
Sign-in administration: setup codes, and each person's sign-in, last sign-in, password link and sessions
Sign-in administration: password links and setup codes, second factors, locks and sessions.
Sign-in administration: setup codes, and each person's sign-in, last sign-in, password link and sessionsSign-in administration: password links and setup codes, second factors, locks and sessions.

2.3 Sign-in

Who may sign in is People & departments' to say: a person active there, nobody else. Someone the plant's identity provider or directory knows, but People & departments does not, is refused by name and told to ask whoever keeps it. How people prove who they are is any of these, together:

WaySettingsNotes
Single sign-on (OpenID Connect)OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETRegister https://<this site>/login/sso/callback with the provider, or set OIDC_REDIRECT_URI. The authorization code flow with PKCE; the ID token's signature, issuer, audience, expiry and nonce are checked. The sign-in id is the preferred_username claim, or OIDC_CLAIM. OIDC_LABEL names the button. Multi-factor is the provider's.
The plant's directory (LDAP, Active Directory)LDAP_URL, LDAP_USER_DNA bind as the person with the password they typed: ldaps://dc.plant:636, and {user}@plant.local (AD) or uid={user},ou=people,dc=plant,dc=example. LDAP_CA_FILE for a plant CA. ldap:// sends passwords in the clear: the server warns.
A password of OpenCore MES's ownon unless PASSWORDS=0For plants without either. IT gives a one-time link, valid 3 days unless PASSWORD_LINK_DAYS or --days says (up to 14): node app/mes/db/password.mjs olga --url https://mes.plant. The person sets it there (12 characters at least) and changes it from their name at the top right; a change signs them out elsewhere.
The pickerdevelopment, DEMO=1, or PICKER=1Anyone as anyone, no password. Never on an instance others can reach.

A person with a password here signs in with it, anyone else through the directory. Five wrong passwords in a row lock the sign-in id for 15 minutes, and 30 wrong tries (a password, a code, a setup code) in 10 minutes from one address hold that address, answered 429 until the oldest is 10 minutes old (SIGN_IN_LIMIT=<tries>/<minutes>, 0 for none; counted by each instance, by the address TRUST_PROXY reads). Sign-ins (and the way), refusals (and why), sign-outs, links and passwords set are in the audit trail under $auth. At start, the server prints the ways that are on. Planned: password ageing, SAML.

2.4 Scaling out

  • A read replica. Writes go to the primary; reads a replica can serve go to it once it has replayed every write this process committed (the replay fence), waiting at most 250 ms before the primary answers instead. Sessions, idempotency keys, the write path and the designer stay on the primary.
  • Several instances. BUS=1 on each: every change's targets reach every instance, so a save on one re-runs the open lists on all. Put a balancer in front that keeps a browser on one instance (its live stream and its calls must meet): app/mes/lb.mjs for a trial (LB_PORT, BACKENDS), HAProxy, nginx or a cloud balancer in production, with the same rule. /healthz answers 503 while an instance drains.
  • Nodes for integration. Every instance is a node: it may plan schedules and run triggers. Tag the ones inside the network that reaches ERP (NODE_TAGS=erp) and keep those services to them (5.11).

app/mes/README.md has the commands and the measurements (a replica took 8.6 times fewer commits off the primary; three instances shared 100 saves a second evenly).