Docs Installation 1
Before you start
On this page
This procedure installs OpenCore MES for a plant: the server, its database, its keys, its first administrator, backups, and the checks before go-live; then laptops, upgrades and suites. Each procedure is a table of steps with what you should see; tick Done as you go, and keep the signed copy with the installation's handover.


How to read a step.
- The words say what to do. The dark box under them holds only commands: one whole command a line, nothing else. Copy the box (its Copy button) or type it line by line, in the order shown.
- Replace what is <in yellow, between angle brackets> before you run a line
(the brackets go too):
<server name>becomesmes.plant.example. - A light box titled File is the content of a file: open the file in an editor (the step's dark box does), paste it there, save. Never paste a file's content into the terminal.
- Where there are two ways (from npm or from the source, a Mac or Windows), each way is a step of its own: do the one that fits, skip the other.
1.1 What you install
PostgreSQL: everything the plant keeps (designs, records, the audit trail, sessions), on the same server, reached over the local socket.
OpenCore MES: one Node process (
app/mes/server.mjs), run by systemd as the user opencore, listening on 127.0.0.1 only. It upgrades its own database at each start.Caddy: HTTPS in front, with a certificate it fetches and renews by itself, and HSTS. The application writes its own Content-Security-Policy.
Backups: nightly, encrypted, kept on the server and copied off it; a restore tested every month (
ops/backup/).1.2 Requirements
| What | Notes | |
|---|---|---|
| Server | Ubuntu 24.04 LTS, x86-64, root access | Sized for your plant (the load figures measured so far are in app/mes/README.md); disk for the database, its backups (14 daily and 12 monthly kept by default) and the event log. |
| Node.js | >=24 (the package's engines) | ops/demo/provision.sh installs the latest release, checked against its published checksum; pin it with NODE_VERSION. |
| PostgreSQL | 16 or later | The test pipeline runs on 16. Ubuntu 24.04's own package is used. |
| Network | A DNS name for the server; ports 80 and 443 open to the plant's users | Outbound: your identity provider or directory, the systems your services call (ERP…), Let's Encrypt, the suites registry if you use suites, the AI provider if you use the copilot. |
| Browsers | Safari 15.4, Chrome 93, Firefox 92 or later | Firefox 114 or later for the rule advice beside a form (older: the server decides at save). |
| Your workstation | SSH with a key to the server | Chrome only if you print these documents as PDF. |
| A laptop (trying it) | A Mac on a macOS Homebrew supports, or Windows 10 (2004 or later) or 11 with WSL 2 | Node and PostgreSQL as above, installed per IN-31 or IN-32. |


1.3 Which way
| Linux server (part 2) | npm plant folder (part 3) | MacBook or Windows laptop (part 3) | |
|---|---|---|---|
| For | Production: a plant's live system | A pilot, a small plant | Trying it, training, a demo, designing offline; never a plant's live system |
| From | A source archive of the version you install (github.com/opencore-mes/opencore-mes) | The npm package @opencore-mes/server (a plant folder holds its settings) | The npm package, or a source archive |
| Runs as | systemd, its own user, HTTPS by Caddy, hardened host | opencore-mes start; production practice is part 2's | From a terminal, on the laptop only (http://localhost:9090) |
| Backups, audit protection, host hardening | Scripts in ops/, used as they are | Not in the package: take ops/ from the source archive of the same version | None: a laptop's data is not backed up by OpenCore MES |
Caution. Versions. The empty installation (
--empty), the first administrator (admin) and the suite commands come with the release this procedure accompanies. The npm package published as 0.1.0 was built before them: with it, a plant folder or a laptop can try the sample plant (IN-33, way A) only; install from a source archive for the rest, or wait for the next package.1.4 Decide first
Write these down before you start; the procedures ask for them.
| Decision | Where it goes | |
|---|---|---|
| 1 | The server's name (e.g. mes.plant.example) | Caddy, the password links (--url) |
| 2 | How people sign in: your identity provider (OpenID Connect), your directory (LDAP or Active Directory), or passwords of OpenCore MES's own with a second factor | OIDC_*, LDAP_*, MFA (7.1) |
| 3 | The first administrator: their sign-in id, as your directory or identity provider knows them (lower case letters, digits, _ and -: an employee number such as 104523 works; a dot does not), and their full name | IN-15 |
| 4 | The first department, which governs the organization (Engineering unless you say otherwise) | --department |
| 5 | The plant's time zone | PLANT_TZ |
| 6 | Where backups are copied off the server: a bucket (rclone: S3, B2, GCS, Azure…) or another host (rsync over SSH), in another provider account than the server's, with credentials that can add files but not delete them | OFFSITE_RCLONE or OFFSITE_RSYNC (IN-18) |
| 7 | Where alerts go (a chat channel's or on-call service's incoming webhook) | ALERT_WEBHOOK_URL |
| 8 | Which hosts services may reach (ERP, the identity provider…) | MES_CONNECTION_HOSTS |
| 9 | Who keeps the keys, and where the offline copies are | IN-13 |
| 10 | The copilot: none, or an AI provider and its key | AI_PROVIDER |
Caution. Never copy the public demo's settings (
ops/demo/demo.env: DEMO=1, guests, SEED_*) nor its reset timer (opencore-mes-reset.timer, which wipes its database every night) to a plant. Take the steps here, not the demo's deploy script as it is.