---
title: "Service containers"
description: "Run a Python model or any other HTTP service in a container next to the app, only reachable from it."
canonical_url: "https://docs.dev.lightdrop.cloud/guides/services"
---
# Service containers

> Run a Python model or any other HTTP service in a container next to the app, only reachable from it.

Some work doesn't fit an isolate: a Python model with native libraries, a Java library, a process
that holds gigabytes in memory. Put it into a container with an HTTP server, add it to the app's
`services`, and call it from the server with `useService()`. wervt builds it with the deploy,
starts it on the first request and stops it again when it idles. Only the app reaches it: it has no
URL of its own and no way in from the internet.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wervt/nuxt'],
  wervt: {
    services: {
      faces: {
        build: './face-service', // a directory with a Dockerfile
        port: 8000,
        health: '/healthz',
        memory: '2GB',
        cpus: 2,
        idle: '10m',
      },
    },
  },
})
```

```ts [server/api/photos/[id]/faces.post.ts]
import { useService } from '@wervt/nuxt/server'

export default defineEventHandler(async (event) => {
  const image = await readRawBody(event, false)
  const res = await useService('faces').fetch('/detect', { method: 'POST', body: image })
  if (!res.ok) throw createError({ status: 502, message: 'Face detection failed' })
  return res.json()
})
```

Apps without Nuxt set the same under `services` in `@wervt/nitro`'s options or in package.json's
`wervt` field for [`wervt build`](https://docs.dev.lightdrop.cloud/api/platform-contract#wervt-build), and import `useService` from
`@wervt/core`.

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        build
      </code>
    </td>
    
    <td>
      –
    </td>
    
    <td>
      A directory with a Dockerfile, relative to the app. <code>
        { context, dockerfile }
      </code>
      
       for another file, its path relative to the context.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        image
      </code>
    </td>
    
    <td>
      –
    </td>
    
    <td>
      A registry image instead of <code>
        build
      </code>
      
      , with a tag or digest: <code>
        ghcr.io/org/ocr:1.4
      </code>
      
      . One of the two is required.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        port
      </code>
    </td>
    
    <td>
      required
    </td>
    
    <td>
      The port it listens on. It also gets it as <code>
        PORT
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        health
      </code>
    </td>
    
    <td>
      –
    </td>
    
    <td>
      A path that answers 2xx once the service is ready, like <code>
        /healthz
      </code>
      
      . Without, an open port counts as ready.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        memory
      </code>
    </td>
    
    <td>
      <code>
        512MB
      </code>
    </td>
    
    <td>
      Its memory limit, at least <code>
        64MB
      </code>
      
      . No swap on top: past it, the container is killed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cpus
      </code>
    </td>
    
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      CPU cores, like <code>
        0.5
      </code>
      
       or <code>
        2
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        idle
      </code>
    </td>
    
    <td>
      the server's, <code>
        10m
      </code>
    </td>
    
    <td>
      How long without requests until it stops, <code>
        1m
      </code>
      
       to <code>
        24h
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        alwaysOn
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Keeps it running instead of stopping it when idle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        egress
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Lets it reach the internet. Without, it can only answer the app.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        env
      </code>
    </td>
    
    <td>
      –
    </td>
    
    <td>
      Up to 50 variables. They're part of the bundle, so no secrets; <code>
        WERVT_
      </code>
      
       names are the platform's.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tmpfs
      </code>
    </td>
    
    <td>
      –
    </td>
    
    <td>
      Up to 4 writable directories besides <code>
        /tmp
      </code>
      
      , like <code>
        /cache
      </code>
      
      , 256 MB each.
    </td>
  </tr>
</tbody>
</table>

Names are lowercase letters, digits and dashes, starting with a letter. A mistake in the options
fails the build, not the deploy. The server sets the most memory and CPU one service may ask for
(4 GB and 2 cores unless the admin changed it); a deploy past that fails and says so.

## Calling it

`useService(name)` returns two things:

- **available**: whether the service exists here, in the active release on wervt or next to the
dev server. Use it to skip the work where it doesn't, such as on a laptop without Docker.
- **fetch(path, init)**: a request to the service, `path` from its root. The answer is the
service's own, whatever its status, streamed both ways, so large uploads and downloads don't sit
in memory.

When the platform couldn't deliver the request, `fetch` throws a `WervtError` instead of returning
an answer: 404 for a name that isn't in the release, 502 or 503 when the container didn't start or
the server doesn't run services. A 404 or 503 the service itself sends comes back as a normal
response, so the two can't be mixed up.

The `authorization` header never reaches the service. It needs none: nothing but the app can call
it.

A stopped service starts on the first request, and that request waits until it's ready, up to the
server's start timeout (2 minutes by default). Bake models into the image instead of downloading
them at start: a container that loads a model from its own files starts in a few seconds.

## Locally

`nuxt dev` (and `nitro dev`, `wervt dev`) builds each service with your local Docker and starts it
on a free port on `127.0.0.1`, in the background, so the dev server doesn't wait for the build.
The container gets the same limits, read-only filesystem and `tmpfs` as on wervt; only `egress`
doesn't apply locally, where containers can reach the internet. It's removed when the dev server
stops.

Without Docker the dev server warns and the service is `available: false`. To use a service you
run yourself, set its address, and the dev server leaves it alone:

```bash
WERVT_SERVICE_FACES_URL=http://127.0.0.1:8000 pnpm dev
```

## Deploys and rollbacks

`wervt deploy` uploads each `build` directory, minus what its `.dockerignore` excludes. The server
builds the image only when the directory's contents changed since the last build; otherwise the
deploy says `faces: unchanged, built before` and reuses it. A `RUN` step gets 2 GB and 2 cores, and a build may take up to
30 minutes.

Before the new release goes live, the deploy starts every service and waits until each is ready:

```text
◆  faces: built
◇  Service faces started in 2957 ms
◆  Release 20261120133618-7279e3, started in 253 ms
```

If one doesn't start, the deploy fails and the app stays on the release before, with its own
containers. A changed image, limit or variable gets a new container; the old one keeps serving
until the new release is live, and stays around stopped for as long as its release is kept, so a
[rollback](https://docs.dev.lightdrop.cloud/guides/deploys) finds it again.

## Watching them

The app's **Services** page in the dashboard shows each service of the active release: whether it's
running, idle (stopped until the next request) or missing, its image, limits and idle time, and
the starts and stops of the last 7 days. **Logs** opens the service's output.

```bash
wervt services my-app                                  # state, limits and idle time
wervt logs my-app 'type:=Service' --since 1h            # everything the services wrote
wervt logs my-app 'type:=Service service:="faces"'      # one service
wervt logs my-app 'type:=Service stream:=runner'        # starts, stops, crashes, out of memory
```

Everything a service writes to stdout and stderr lands in the app's [logs](https://docs.dev.lightdrop.cloud/guides/logs) with
`type:=Service` and its name in `service`. JSON lines keep their fields, and their `level` and
`message` (or `msg`) become the entry's. The platform's own entries about a service (started, stopped
when idle, exited with a code, ran out of memory) have `stream:=runner`.

## Limits

Service containers are off for accounts until an admin gives them memory: the account's apps may
ask for that much memory for their services together. Apps of admins have no limit.

```bash
wervt accounts friend@example.com --services 4GB
wervt accounts friend@example.com --services 0         # off again
```

A deploy whose services would take the account past its limit is refused. Only the active
releases' services count, not the stopped containers kept for rollbacks.

## What a service can't do

Containers run with a fixed profile that no option loosens:

- a read-only filesystem, with `/tmp` and the `tmpfs` paths as the only writable places, emptied
when the container stops. Keep data in the app's [database](https://docs.dev.lightdrop.cloud/guides/database) or
[files](https://docs.dev.lightdrop.cloud/guides/files).
- no capabilities, no new privileges, no mounts or devices, at most 256 processes
- their own network per service: no internet without `egress`, and never another app's containers
- no way into the platform's own network: the runner that starts the containers drops their
connections

Builds from a Dockerfile run on the server with network access for `RUN` steps, which is why
service containers are only for accounts an admin trusts with them.


## Sitemap

See the full [sitemap](https://docs.dev.lightdrop.cloud/sitemap.md) for all pages.
