- 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 ofresources. 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 inports, 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 always3000, so itsportslists3000first, then any extra ports:[3000, 9090]. - Every port is reachable from the environment’s other services, and any of them can take a hostname.
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.
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
- 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.
- 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.
- 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 itswatchPaths, relative to the project
root. Then a deploy rebuilds the service only when:
- a file under one of its
watchPathschanged; envchanged;- its base image (
node-22-slim, or its Dockerfile’s lastFROM) was republished since its last build, unless thatFROMis pinned by digest (@sha256:); - one of these keys of its entry changed:
- a Node.js service:
image,root,build,startorstatic; - a Dockerfile service:
rootordockerfile.
- a Node.js service:
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 setswatchPaths, and every deploy rebuilds both:
modelence.config.json
"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
apps/api rebuilds only api. A change in packages/shared or the lockfile rebuilds
both.