Skip to main content
An environment can run multiple services: a web app next to an API in another language, or a background worker next to the site. Each service is built its own way, Node.js or Dockerfile, and runs in containers of its own. The services share a private network that no other environment can reach.
  • An environment runs up to 5 services. More than one needs a paid plan.
  • Multiple services are for different processes. To run more copies of the same process, raise the service’s container count in the dashboard instead.

The file

Each service is one entry of resources. This app has a Node.js site in web/ and a Python API in ml/ that only the site calls:
modelence.config.json
web reads the API’s address from ML_URL. With the environment’s URL attached to web, ml can’t be reached from the internet.

Ports

A service lists the ports it listens on in ports, main port first. Without it, a service listens on 3000.
  • The main port is the one the container gets as PORT, and the one the health check probes. A Node.js service’s main port is always 3000, so its ports lists 3000 first, then any extra ports: [3000, 9090].
  • Every port is reachable from the environment’s other services, and any of them can take a hostname.
A service can list up to 10 ports.

Domains

Which service and port a hostname goes to is set in the dashboard, under Domains, not in the file, so the same file can deploy to every environment. That holds for the environment’s own URL (<app>-<environment>.cloud.modelence.app) and for each custom domain. One service can take multiple hostnames on different ports, for example a site on its main port and an admin UI on another.
  • The first deploy attaches the environment’s URL to the main port of the first service in the file. Change it in Domains at any time.
  • A custom domain is attached when you add it. A domain added without a target follows the environment’s URL.
  • The environment’s URL can be detached, for an environment that runs only workers. It then has no public address.
  • Changing a target moves the hostname at once when the service already listens on that port. If it doesn’t yet, the hostname moves when the deploy that adds the port takes over.
Hostnames carry HTTP traffic only. A service or port with no hostname attached is reached only from the environment’s other services. A deploy that removes a service or a port that a hostname is attached to is refused before it builds. Attach the hostname elsewhere first, or keep the service or port.

Reaching another service

A service gets another’s address from a variable of "type": "resource" that names it:
Every service gets every variable, so any service can read WORKER_URL. Calls on the private network are plain HTTP. Don’t hardcode an address: it contains the environment’s id, so it differs in every environment. To reach another port than the main one, combine host with that port. The host is the service’s name in lowercase, with _ written as -. So a service’s name must end in a letter or a digit, and two names can’t differ only in case or in _ and -.

What a deploy does

  1. It builds the services one after another, in the order of the file. If one fails to build, the deploy stops and no service is updated.
  2. It rolls out each service on its own. If one service’s new version fails to start, that service goes back to the version it ran before, and the others keep their new version. The deploy is marked failed, naming the service.
  3. It deletes the services removed from the file, once the deploy has finished. Renaming a service creates a new service and deletes the old one.

What a deploy rebuilds

By default, every deploy rebuilds and restarts every service. To rebuild a service only when its code changes, list the files and folders it is built from in its watchPaths, relative to the project root. Then a deploy rebuilds the service only when:
  • a file under one of its watchPaths changed;
  • env changed;
  • its base image (node-22-slim, or its Dockerfile’s last FROM) was republished since its last build, unless that FROM is pinned by digest (@sha256:);
  • one of these keys of its entry changed:
    • a Node.js service: image, root, build, start or static;
    • a Dockerfile service: root or dockerfile.
A change to its healthCheck, rollout or stopTimeout, and for a Dockerfile service to its start, and a change to any service’s ports, restarts it without a rebuild. A service that is neither rebuilt nor restarted keeps running as it is. Nothing is added to watchPaths for you: not the service’s own root, not the lockfile, not other files at the project root. List everything the service’s build reads: its own folder, any shared code it imports, and the package.json and lockfile it installs from. A change outside its watchPaths never rebuilds it, so a path left out keeps the service on old code. A path that doesn’t exist fails the deploy. npx modelence@latest deploy --rebuild-all rebuilds and restarts every service, whatever its watchPaths.

Scaling and billing

Each service’s container count and container type are set in the dashboard, under the service’s Configure. Each service is billed for its own containers.

Running locally

modelence dev runs one service, so it refuses a file with multiple services. Start each service with its own command instead, in its own terminal.

Examples

A site and a background worker in one Node.js project. Both build from the whole project, so neither sets watchPaths, and every deploy rebuilds both:
modelence.config.json
The worker listens on no port, so it has no health check. "rollout": "recreate" stops the old worker before the new one starts, so a job is never taken by both versions. Keep the worker on one container if its jobs must not run twice, or have each job take a lock in the database. An npm workspaces monorepo with a site and an internal API that both import packages/shared:
modelence.config.json
A change in apps/api rebuilds only api. A change in packages/shared or the lockfile rebuilds both.