OpenCore MES Try the demo

Docs Installation 3

A plant folder, a MacBook, a Windows laptop

On this page

The npm package is the application, ready to run; a plant folder holds an installation's settings (.env), its suites and its event log, outside the package. Use it for a pilot or a small plant. For production, run it as part 2 does (systemd, its own user, Caddy, backups, hardening).

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.
IN-30Install from npm
PurposeOpenCore MES from its npm package, in a plant folder.
Done byIT
Before you start
  • Node 24 or later; PostgreSQL 16 or later, with a role that may create databases, reached over the local socket or DATABASE_URL.
#Do thisYou should seeDone
1On a Mac, only if Node came from the nodejs.org installer (Homebrew's Node and nvm need nothing): give npm a folder of your own, so the install below does not fail with EACCES. Once per Mac.
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
npm config get prefix then says your ~/.npm-global.
2On Linux or Windows (Ubuntu), only if Node came from Ubuntu's packages (nvm needs nothing): the same, for bash. Once per machine.
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
The same.
3Install the package.
npm install -g @opencore-mes/server
opencore-mes version
opencore-mes version answers.
4Make a plant folder, and go into it.
opencore-mes init my-plant
cd my-plant
.env (mode 0600: the settings, commented), suites/, copilot/, .local/.
5Open .env in an editor and set DATABASE_URL (postgres:///opencore_mes unless changed), PROD=1, how people sign in, PLANT_TZ, and SEAL_KEY_FILE and INTEGRITY_KEY_FILE (keys made as in IN-13, kept outside the folder); save and leave.
nano .env
—
6Make the empty database.
opencore-mes db reset --yes --empty
Cannot be undone. It makes the database named in .env again: everything in it is lost. Check DATABASE_URL in .env names a new database.
An empty database.
7Name the first administrator.
opencore-mes admin <id> "<Full name>" --url https://<server name>
Cannot be undone. Once per installation: check the sign-in id and the name first.
The first administrator, a one-time link, setup open (as IN-15).
8Start it, from inside the folder.
opencore-mes start
listening on …; the sign-in page at the address.
9For scripts walled in (Linux): see where the package is, then set SCRIPT_RUNNER_WRAP in .env to <that folder>/@opencore-mes/server/ops/script-runner-sandbox.sh (an absolute path), and install its AppArmor profile beside it as in IN-16.
npm root -g
/healthz: "network":"none".
Caution. The package holds the application and the script runner's walls only. Backups, the audit trail's protection and host hardening are in ops/ of the source archive of the same version: use them as in IN-11, IN-17 and IN-18, with this folder's database.

3.1 On a laptop

A laptop runs the same OpenCore MES, for trying it, training, a demo or designing offline. It is never a plant's live system: nothing backs its data up, it sleeps when its lid closes, and nobody else should reach it. Prepare the laptop (IN-31 on a Mac, IN-32 on Windows), then IN-33.

IN-31Prepare a MacBook
PurposeNode and PostgreSQL on macOS (Apple silicon or Intel), in Terminal.
Done byWhoever uses the laptop
Before you start
  • A macOS that Homebrew supports; an administrator's account; Homebrew installed (it prints the line that adds it to your PATH: run it).
#Do thisYou should seeDone
1Node 24 or later, from the macOS installer at nodejs.org (LTS), or from Homebrew. Then, in a new Terminal window, check it.
node -v
v24.… or later (>=24).
2Only if Node came from the nodejs.org installer: give npm a global folder of your own. Otherwise installing a package for every user fails with EACCES on /usr/local/lib/node_modules; never work around it with sudo.
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
npm config get prefix
Your ~/.npm-global.
3PostgreSQL, started now and with the Mac.
brew install postgresql@17
brew services start postgresql@17
Successfully started postgresql@17.
4Check that PostgreSQL lets you in. (If psql is not found, the next step.)
psql -d postgres -c 'select current_user'
Your macOS user name: Homebrew's PostgreSQL lets you in as yourself, over its local socket, as a superuser. So postgres:///<database> needs no password here.
5Only if psql was not found: see where Homebrew put PostgreSQL, add the bin folder it names to your PATH as it says, open a new Terminal, and do the step before again.
brew info postgresql@17
The folder, and the line to add.
The script runner's operating-system walls are Linux's (bubblewrap): on a Mac scripts run inside Node's own permission model only, and /healthz says so. That is fine on a laptop; never set SCRIPT_ISOLATION=required there.
IN-32Prepare a Windows laptop
PurposeOpenCore MES on Windows 10 or 11, inside WSL 2 (Ubuntu running inside Windows): everything then runs on Linux, as on a server.
Done byWhoever uses the laptop
Before you start
  • Windows 10 (version 2004 or later) or Windows 11; an administrator's account; virtualisation on in the firmware (it is on most laptops).
#Do thisYou should seeDone
1In PowerShell, opened as administrator: install Ubuntu in WSL. Restart Windows when asked.
wsl --install -d Ubuntu-24.04
Ubuntu opens and asks for a Linux user name and password (your own, for this laptop).
2From here on, in Ubuntu (Start → Ubuntu): PostgreSQL, and bubblewrap for the script runner's walls.
sudo apt-get update
sudo apt-get install -y postgresql bubblewrap
PostgreSQL 16 installed.
3Start PostgreSQL, and let your Linux user in (a superuser, on a laptop only).
sudo service postgresql start
sudo -u postgres createuser --superuser "$USER"
CREATE ROLE: postgres:///<database> needs no password for you.
4Node 24 or later in Ubuntu: from nodejs.org (Download → Linux, with a version manager such as nvm). Then check it.
node -v
v24.… or later (>=24).
5Only if Node came another way (Ubuntu's packages, a tarball in /usr): give npm a global folder of your own. Otherwise installing a package for every user fails with EACCES. With nvm, skip this step.
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
npm config get prefix
Your ~/.npm-global.
6Each time Windows restarts, in Ubuntu, before starting OpenCore MES:
sudo service postgresql start
—
Work inside Ubuntu's own folders (~), not on /mnt/c: it is much faster. Open the address it prints in a browser on Windows: WSL passes localhost through. If it does not open, set HOST=0.0.0.0 in the settings: WSL's network stays inside the laptop unless you forward it, but never leave the sample people's picker on a network others reach. OpenCore MES on Windows outside WSL is not tested.
The sign-in page of a plant's server: a username and a password, and I have a setup code
The sign-in page, as a plant's server shows it: a username and a password; a setup code for someone with no password yet.
The sign-in page of a plant's server: a username and a password, and I have a setup codeThe sign-in page, as a plant's server shows it: a username and a password; a setup code for someone with no password yet.
IN-33Install and run it on a laptop
PurposeOpenCore MES running on the laptop: the sample plant to try it (way A), or an empty plant of your own (way B). From npm, or from a source archive: do the steps for one, skip the other's.
Done byWhoever uses the laptop
Before you start
  • IN-31 or IN-32 done. In Terminal (Mac) or Ubuntu (Windows).
#Do thisYou should seeDone
1From npm. On a Mac, only if Node came from the nodejs.org installer (Homebrew's Node and nvm need nothing): give npm a folder of your own, so the install below does not fail with EACCES. Once per Mac.
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
npm config get prefix then says your ~/.npm-global.
2From npm. On Linux or Windows (Ubuntu), only if Node came from Ubuntu's packages (nvm needs nothing): the same, for bash. Once per machine.
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
The same.
3From npm: install the package, make a plant folder, go into it.
npm install -g @opencore-mes/server
opencore-mes init my-plant
cd my-plant
A plant folder with its .env.
4From npm, way A (the sample plant): make the database with the sample people (Dana, Iris, Sam…) and plant (lots, machines, work orders).
opencore-mes db reset --yes
Cannot be undone. It makes the database named in .env again: everything in it is lost. On a laptop's own new database only.
It says what it loaded.
5From npm, way B (a plant of your own): its two keys, outside the plant folder, named in its .env (with PROD=1 it does not start without them).
mkdir -p "$HOME/.opencore-mes-keys"
openssl rand -hex 32 > "$HOME/.opencore-mes-keys/seal.key"
openssl rand -hex 32 > "$HOME/.opencore-mes-keys/integrity.key"
chmod 0400 "$HOME"/.opencore-mes-keys/*.key
echo "SEAL_KEY_FILE=$HOME/.opencore-mes-keys/seal.key" >> .env
echo "INTEGRITY_KEY_FILE=$HOME/.opencore-mes-keys/integrity.key" >> .env
Cannot be undone. Once per laptop. Run again, the keys are replaced: second factors set up with the old seal key can no longer be read.
Two files of 64 hex characters in ~/.opencore-mes-keys, readable by you only; .env names them.
6From npm, way B: the empty database, and its first administrator.
opencore-mes db reset --yes --empty
opencore-mes admin <id> "<Full name>" --url http://localhost:9090
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.
The first administrator, and a one-time link to set their password; setup open.
7From npm: start it. For way B add PROD=1 to .env first, for the real sign-in page.
opencore-mes start
… listening on http://127.0.0.1:9090 …
8From a source archive: get the source and its dependencies.
git clone https://github.com/opencore-mes/opencore-mes.git
cd opencore-mes
npm ci
The source, with its five dependencies.
9From source, way A: the database with the sample plant.
DATABASE_URL=postgres:///opencore_mes node app/mes/db/reset.mjs
Cannot be undone. It makes the database opencore_mes again: everything in it is lost.
It says what it loaded.
10From source, way B: its two keys, outside the source folder (with PROD=1 it does not start without them).
mkdir -p "$HOME/.opencore-mes-keys"
openssl rand -hex 32 > "$HOME/.opencore-mes-keys/seal.key"
openssl rand -hex 32 > "$HOME/.opencore-mes-keys/integrity.key"
chmod 0400 "$HOME"/.opencore-mes-keys/*.key
Cannot be undone. Once per laptop. Run again, the keys are replaced: second factors set up with the old seal key can no longer be read.
Two files of 64 hex characters in ~/.opencore-mes-keys, readable by you only.
11From source, way B: the empty database, and its first administrator, sealed with those keys.
SEAL_KEY_FILE=$HOME/.opencore-mes-keys/seal.key INTEGRITY_KEY_FILE=$HOME/.opencore-mes-keys/integrity.key DATABASE_URL=postgres:///opencore_mes node app/mes/db/reset.mjs --empty
SEAL_KEY_FILE=$HOME/.opencore-mes-keys/seal.key INTEGRITY_KEY_FILE=$HOME/.opencore-mes-keys/integrity.key DATABASE_URL=postgres:///opencore_mes node app/mes/db/admin.mjs <id> "<Full name>" --url http://localhost:9090
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.
The first administrator, and a one-time link to set their password; setup open.
12From source, way A: start it, on this laptop only.
HOST=127.0.0.1 DATABASE_URL=postgres:///opencore_mes node app/mes/server.mjs
… listening on http://127.0.0.1:9090 (development …)
13From source, way B: start it, on this laptop only, with the real sign-in page.
SEAL_KEY_FILE=$HOME/.opencore-mes-keys/seal.key INTEGRITY_KEY_FILE=$HOME/.opencore-mes-keys/integrity.key HOST=127.0.0.1 PROD=1 DATABASE_URL=postgres:///opencore_mes node app/mes/server.mjs
… listening on http://127.0.0.1:9090 (production …). Without the keys it stops at once: Not starting: PROD=1 and no SEAL_KEY ….
14Open http://localhost:9090. Way A: pick who you are. Way B: open the password link first. With PROD=1 over plain http://localhost, use Chrome, Edge or Firefox: the sign-in cookie is marked Secure, which they accept on localhost.Way A: the people to pick from (no passwords: a development instance). Way B: the sign-in page.
15To stop it: Ctrl+C in the terminal where it runs. To start again: the start step above.—

To remove it, the database, then the folder; and, if nothing else uses them, the package and PostgreSQL (on Windows, unregistering Ubuntu removes the whole Ubuntu, everything in it included):

dropdb opencore_mes
Cannot be undone. The database and everything in it are deleted.
npm uninstall -g @opencore-mes/server
brew services stop postgresql@17
brew uninstall postgresql@17

On Windows, in PowerShell:

wsl --unregister Ubuntu-24.04
Cannot be undone. The whole Ubuntu is deleted: OpenCore MES, its database, and every other file in it.
Caution. A development instance (without PROD=1) lets anyone who reaches it sign in as anyone. Keep it on 127.0.0.1 on a laptop: the plant folder's .env says so already; from source, HOST=127.0.0.1 as in the start steps. It warns at start when it is reachable from other machines.