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
buildcommands and starts thestartcommands. - 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.
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 missingbuild 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.
planis 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.
Variables
Every service gets these variables at start:MONGODB_URIandMONGO_URL: a MongoDB Atlas database provisioned for this environment (both hold the same connection string).SITE_URLandROOT_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
envties to a resource, such asDATABASE_URLfrom a PostgreSQL database’surl.
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"] }.