Deploy

Run your connector on a laptop, VM, or server you control. You manage build, configuration, and runtime artifact deployment.

Prerequisites: A completed Scaffold-generated connector project.

Skeletal deploy is valid

You run a skeletal connector on your host to prove build, config, and network paths, then iteratively implement ERP-specific work appropriate for your facility. ERP references and connector requirements can continue to grow after this POC.

Overview

Self-hosted deployment means running the built connector process on a host you operate. The minimum requirement is a machine with Node.js (and any ERP-specific dependencies your connector needs, starting with some simple POC test), the project built from your scaffold, and environment variables configured.

Typical workflow:

1. Install dependencies and build the TypeScript project (npm install, npm run build).
2. Configure environment variables from .env.example.
3. Start the connector process on the host (npm run start or the command your README documents).
4. Verify the process stays up and can reach MachineMetrics and your ERP.

Your generated README.md describes local commands and required variables. Use it as the repo-local source of truth; this page covers deployment context and networking.

Run on the host (laptop, VM, or server)

From your connector project root:

npm install
npm run build
cp .env.example .env   # then edit .env with production values
npm run start

Install Node.js and any native or ODBC drivers your ERP connection requires on that machine — the same prerequisites you use during development. A developer laptop is a valid self-hosted environment for trials; a dedicated VM or server can be used for production.

Configure environment

Set values in .env (or your process manager / secret store) for:

• MachineMetrics API credentials and endpoints, at least:
  • MM_MAPPING_SERVICE_URL
  • MM_MAPPING_AUTH_SERVICE_URL
  • MM_MAPPING_SERVICE_TOKEN (an API Key created in MachineMetrics App with scope user+erp+reporting)
• ERP connection settings (URLs, database hosts, API keys, etc.)
• Connector-specific feature flags documented in your README

Do not commit production secrets to source control.

Verify

Confirm the process keeps running and logs show:

• Successful startup (no immediate exit from missing env vars)
• Connectivity to MachineMetrics API endpoints
• Connectivity to your ERP (database, REST API, or other transport)

Success signal

Use the SDK logging mechanism — MMConnectorLogger in @machinemetrics/mm-erp-sdk — to send startup, heartbeat, and status messages to the Connector Log. Wire this during implementation (see CONNECTOR_SDK_UTILITIES.md in your project). While the file logging mechanism should be used liberally, do not flood this log.

After the connector is running, confirm deployment success in the Connector Logs tab of the MachineMetrics app. An identifiable startup or heartbeat message from your connector is evidence that the skeleton is alive and communicating with MachineMetrics (and your ERP, once configured).

Docker (advisable, not required)

Containerizing with the template Dockerfile is recommended for repeatable deployments, dependency isolation, and production handoff — but it is not required. A self-hosted connector can be run directly with Node on a VM or even a laptop during development and pilot rollouts.

If you use Docker:

docker build -t {name}-connector:local .
docker run --env-file .env -p <host-port>:<container-port> {name}-connector:local

Modify the template Dockerfile for connector-specific requirements (base image, OS packages, build steps). Treat it as a starting point, not a fixed recipe. See your project README for port mapping and run flags.

Template README

Your generated README.md covers:

• Prerequisites and local npm commands
• Pointers to CONNECTOR-GUIDE.md and SDK reference files
• Environment variable overview

Reference implementation

For a worked example connector (epicor-ten-connector) and its caveats, see Documentation → Reference implementation.

Networking prerequisites

The host running the connector must reach both MachineMetrics and your ERP.

MachineMetrics API

Requirement	Notes
Outbound HTTPS	Host must reach api.machinemetrics.com (or api.machinemetrics-us-gov.com for GovCloud)
Credentials	Valid API/OAuth credentials configured in environment
Firewall / proxy	Allow outbound traffic from the connector host; configure proxy env vars if required

ERP connectivity

Requirement	Notes
ERP endpoint reachability	Database port, REST base URL, ODBC source, or file drop location accessible from the connector host
Credentials	Dedicated ERP service account with least privilege for read/write operations your connector performs
Latency and stability	Long-running sync jobs need stable network paths between host and ERP

Document ERP-specific ports and allowlists with your infrastructure team before production cutover.