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).


| Purpose | OpenCore MES from its npm package, in a plant folder. |
|---|---|
| Done by | IT |
| Before you start |
|
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | 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. | |
| 2 | 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. | |
| 3 | Install the package.npm install -g @opencore-mes/server opencore-mes version | opencore-mes version answers. | |
| 4 | Make a plant folder, and go into it.opencore-mes init my-plant cd my-plant | .env (mode 0600: the settings, commented), suites/, copilot/, .local/. | |
| 5 | Open .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 | — | |
| 6 | Make 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. | |
| 7 | Name 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). | |
| 8 | Start it, from inside the folder.opencore-mes start | listening on …; the sign-in page at the address. | |
| 9 | For 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". |
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.
| Purpose | Node and PostgreSQL on macOS (Apple silicon or Intel), in Terminal. |
|---|---|
| Done by | Whoever uses the laptop |
| Before you start |
|
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | Node 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). | |
| 2 | Only 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. | |
| 3 | PostgreSQL, started now and with the Mac.brew install postgresql@17 brew services start postgresql@17 | Successfully started postgresql@17. | |
| 4 | Check 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. | |
| 5 | Only 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. |
/healthz says so. That is fine on a laptop; never set SCRIPT_ISOLATION=required there.| Purpose | OpenCore MES on Windows 10 or 11, inside WSL 2 (Ubuntu running inside Windows): everything then runs on Linux, as on a server. |
|---|---|
| Done by | Whoever uses the laptop |
| Before you start |
|
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | In 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). | |
| 2 | From 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. | |
| 3 | Start 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. | |
| 4 | Node 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). | |
| 5 | Only 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. | |
| 6 | Each time Windows restarts, in Ubuntu, before starting OpenCore MES:sudo service postgresql start | — |
~), 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.

| Purpose | OpenCore 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 by | Whoever uses the laptop |
| Before you start |
|
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | From 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. | |
| 2 | From 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. | |
| 3 | From 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. | |
| 4 | From 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. | |
| 5 | From 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. | |
| 6 | From 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. | |
| 7 | From 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 … | |
| 8 | From 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. | |
| 9 | From 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. | |
| 10 | From 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. | |
| 11 | From 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. | |
| 12 | From 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 …) | |
| 13 | From 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 …. | |
| 14 | Open 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. | |
| 15 | To 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
npm uninstall -g @opencore-mes/server
brew services stop postgresql@17 brew uninstall postgresql@17
On Windows, in PowerShell:
wsl --unregister Ubuntu-24.04
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.