Skip to main content
modelence.config.json sits at the project root and is the whole contract between the project and Modelence Cloud. Comments (//, /* */) and trailing commas are allowed. Apart from a resource’s type, every key is optional; a missing key takes the default. To set a project up step by step, follow Deploy Setup. This page lists every key.

Top level

Services

A resource with "type": "service" is a process built from this repository and run in containers of its own. A service is built one of two ways:
  • Node.js (the default): Modelence Cloud builds the image on an official Node.js image, runs the build commands and starts the start commands.
  • Dockerfile: the service sets dockerfile, and the project’s own Dockerfile builds the image. Use it for any language, or for a Node.js app that needs system packages. See Dockerfile services.
An environment runs up to 5 services. More than one needs a paid plan. See Multiple services.

Keys of every service

Keys of a Node.js service

The process must listen on the port in the PORT environment variable. A hardcoded port never receives traffic.

Keys of a Dockerfile service

Health checks

A container is checked every 5 seconds. 10 failures in a row replace it, and a deploy whose new containers never become healthy rolls the service back. tcp and http take gracePeriod: the seconds after a container starts during which failed checks don’t count, 0 to 300, default 60. Raise it for an app that loads a model or warms a cache before it listens. The check connects from outside the container, so the process must listen on 0.0.0.0, not only on 127.0.0.1.

Missing, empty and none

A missing build runs npm install; "build": { "commands": [] } means there is no build step. A missing start means no process for a Node.js service, and the Dockerfile’s own CMD for a Dockerfile service. An empty command string "" is invalid and is rejected.

Managed resources

A database, cache or telemetry endpoint that a deploy creates in the environment. PostgreSQL and Redis need a paid plan. Telemetry needs a plan with monitoring (Pro and up). It gives the environment a private OpenTelemetry endpoint for the app’s traces and metrics, kept for 30 days and shown on the environment’s Monitoring page. Logs need no setup: the app’s output is collected and shown on the Logs page. A deploy creates every managed resource the file declares that the environment doesn’t have yet, and the new version starts only once they are ready. Resources are matched by name, so the same file works in every environment:
  • A resource that already exists is kept as it is, with its data. plan is read only when the resource is created, so changing it later has no effect.
  • A resource removed from the file is not deleted. Delete it in the dashboard under Resources when it is no longer needed; a database or cache is billed until then.
  • Renaming a resource creates a new, empty one. The old one stays until it is deleted.
An environment can have up to 10 managed resources, telemetry included, and at most one of them can be telemetry.

Variables

Every service gets these variables at start:
  • MONGODB_URI and MONGO_URL: a MongoDB Atlas database provisioned for this environment (both hold the same connection string).
  • SITE_URL and ROOT_URL: the environment’s public URL (both hold the same value).
  • PORT: the service’s main port, which the process must listen on.
  • Any variables the user defines in the dashboard under Environment variables.
  • The variables env ties to a resource, such as DATABASE_URL from a PostgreSQL database’s url.
Names starting with MODELENCE_, and PORT, are reserved and cannot be defined by the user. Each entry of env declares one variable: A value set in the dashboard overrides a value written here, so a literal in the file is the committed default rather than a fixed constant. Every service of the environment gets every variable.

Resource variables

A variable with "type": "resource" takes its value from one output of a managed resource or of another service in the same file, and takes only these keys: The url output is a full connection string: postgresql://...?sslmode=require for PostgreSQL and rediss://... (TLS) for Redis. The other outputs are its parts, for clients that read them separately, such as PGHOST and PGPASSWORD. These variables reach the running app only, not the build. They can’t be set or changed in the dashboard, where they are listed with the resource they come from. A service’s outputs are its private address: url is http://<host>:<port> on its main port, for example http://worker.<environment id>.cloud.local:3000, and host reaches every one of its ports. Only the environment’s other services reach it. See Multiple services. Telemetry’s outputs are the values of the standard OpenTelemetry variables: endpoint for OTEL_EXPORTER_OTLP_ENDPOINT and headers for OTEL_EXPORTER_OTLP_HEADERS, which holds the environment’s credentials. The endpoint takes OTLP over HTTP and is private: only the running app reaches it, not the build or a local machine.
Apps built on the Modelence framework need no file: npx modelence@latest deploy recognizes the modelence dependency and keeps building them locally, as it always has. To build one on Modelence Cloud instead, describe it like any other Node.js app: "build": { "commands": ["npm ci", "npm run build"] } and "start": { "commands": ["npm start"] }.