> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiple services

> Run a web app, APIs and workers side by side in one environment

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](https://docs.modelence.com/deploy/dockerfile.md), 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:

```json modelence.config.json theme={null}
{
  "$schema": "https://cloud.modelence.com/schema/modelence.config.json?version=1",
  "resources": {
    "web": {
      "type": "service",
      "root": "web",
      "build": { "commands": ["npm ci", "npm run build"] },
      "start": { "commands": ["node server.js"] },
      "watchPaths": ["web"]
    },
    "ml": {
      "type": "service",
      "root": "ml",
      "dockerfile": "Dockerfile",
      "ports": [8000],
      "watchPaths": ["ml"]
    }
  },
  "env": {
    "ML_URL": { "type": "resource", "resource": "ml", "output": "url" }
  }
}
```

`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:

```json theme={null}
"env": {
  "WORKER_URL": { "type": "resource", "resource": "worker", "output": "url" }
}
```

| Output | Value |
| - | - |
| `url` | `http://<host>:<port>` on the main port, such as `http://worker.<environment id>.cloud.local:3000` |
| `host` | `worker.<environment id>.cloud.local`. It reaches every port in the service's `ports`. |
| `port` | The service's main port: the first of its `ports`, `3000` without them. |

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:

```json modelence.config.json theme={null}
{
  "$schema": "https://cloud.modelence.com/schema/modelence.config.json?version=1",
  "resources": {
    "web": {
      "type": "service",
      "build": { "commands": ["npm ci", "npm run build"] },
      "start": { "commands": ["node dist/server.js"] }
    },
    "worker": {
      "type": "service",
      "build": { "commands": ["npm ci", "npm run build"] },
      "start": { "commands": ["node dist/worker.js"] },
      "healthCheck": { "type": "none" },
      "rollout": "recreate"
    },
    "queue": { "type": "redis" }
  },
  "env": {
    "REDIS_URL": { "type": "resource", "resource": "queue", "output": "url" }
  }
}
```

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`:

```json modelence.config.json theme={null}
{
  "$schema": "https://cloud.modelence.com/schema/modelence.config.json?version=1",
  "resources": {
    "web": {
      "type": "service",
      "build": { "commands": ["npm ci", "npm run build -w apps/web"] },
      "start": { "commands": ["node apps/web/dist/server.js"] },
      "watchPaths": ["apps/web", "packages/shared", "package.json", "package-lock.json"]
    },
    "api": {
      "type": "service",
      "build": { "commands": ["npm ci", "npm run build -w apps/api"] },
      "start": { "commands": ["node apps/api/dist/server.js"] },
      "watchPaths": ["apps/api", "packages/shared", "package.json", "package-lock.json"]
    }
  },
  "env": {
    "API_URL": { "type": "resource", "resource": "api", "output": "url" }
  }
}
```

A change in `apps/api` rebuilds only `api`. A change in `packages/shared` or the lockfile rebuilds
both.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.