Service Behavior

Treat services as declared readiness dependencies, not hidden setup steps.

Use this page when a repo needs supporting infrastructure such as a database, cache, queue, or local API before tasks can run safely.

• a service is part of the readiness contract, not just an implementation detail
• the service block should say what starts, what stops, what depends on what, and how readiness is checked
• ota doctor can tell you whether the repo is actually ready
• ota up can bring required services up before setup runs
• CI and agents can see startup dependencies instead of guessing

Every service has a lifecycle: start it, check it, and stop it.

ota only trusts a service as ready after the declared healthcheck succeeds.

• start is the command ota can use to bring the service up
• healthcheck is the command ota uses to prove the service is actually usable
• stop is the command ota can use to shut the service down later
• depends_on controls start order, but it does not replace readiness checks

Each field exists to remove one guess from the readiness story.

• required: whether the service blocks repo readiness when it fails
• manager is the preferred control-plane contract for service orchestration.
• manager.kind is host or compose.
• For Compose managers, manager.name and manager.service are required; services.<name>.manager.file / services.<name>.manager.files and services.<name>.manager.env_file / services.<name>.manager.env_files are optional service-owned adapter inputs.
• Keep manager.name aligned with the Compose project name you actually use. Drift between manager.name, attachments.compose, and manual docker compose -p ... usage will break persistent container attachments and service reachability.
• Example: if the repo naturally runs as qredex-core, use manager.name: qredex-core, keep attachments.compose: [qredex-core], and use the same Compose project name in manual commands.
• provider is legacy compatibility for host-bound service control; provider: docker-compose wraps only healthcheck with docker compose exec, while start and stop are taken directly from declaration.
• start: the command ota uses to start the service; when manager.kind is compose this is derived automatically from compose context, otherwise start must be explicit.
• stop: the command ota uses to stop the service; when manager.kind is compose this is derived automatically from compose context, otherwise stop must be explicit.
• healthcheck: the command ota uses to prove the service is ready; if manager is set, this is adapted to manager-aware execution automatically
• depends_on: the services that must start before this one is attempted
• timeout: how long ota waits for the healthcheck before treating it as slow or failed

• ota services inspects the declared service surface
• ota doctor checks healthchecks and reports whether the repo is truly ready
• ota up starts required services before setup and uses the declared order
• ota detect can infer high-confidence service fields from Compose files when the repo does not declare them explicitly
• optional services remain visible, but they do not block the repo if they fail
• manager does not invent services, but it does derive command wiring from its kind so control-plane behavior is consistent.

• if a required service fails its healthcheck, the repo is not ready
• if an optional service fails its healthcheck, ota reports it but does not make the repo unusable
• ota up starts required services in dependency order before setup
• ota doctor uses healthchecks to decide whether readiness is real or just assumed
• ota services lists the declared service surface without starting anything
• depends_on is an ordering hint, not a readiness guarantee by itself

This example shows a repo that needs Postgres and Redis before the app can run.

services:  postgres:    required: true    manager:      kind: compose      file: compose.yaml      service: postgres    healthcheck: pg_isready -h localhost -p 5432    timeout: 5000  redis:    required: false    manager:      kind: compose      file: compose.yaml      service: redis    healthcheck: redis-cli ping    timeout: 3000  api:    required: true    manager:      kind: compose      file: compose.yaml      service: api    depends_on:      - postgres      - redis    healthcheck: curl -fsS http://localhost:3000/health    timeout: 5000

• the repo becomes ready only after required services pass their checks
• the service order is driven by declared dependencies, not shell script order
• the healthcheck command decides readiness, not just whether the service process exists
• a slow healthcheck can fail via timeout even if the service eventually comes up
• manager-based services do not invent services or run guesses; they derive the service command wiring from kind and the manager fields
• the same service declaration should explain behavior to humans and agents

• a repo needs a database before tests can run
• a team wants optional local infra visible without making it blocking
• a maintainer wants up to bring services up before setup
• CI needs to surface service drift as a clear readiness issue
• an agent needs to know whether it can trust a local app to be live before starting work
• a repo uses docker-compose for the local stack but still wants ota to own readiness checks

• does not invent services that are not declared
• does not guess dependency ordering beyond depends_on
• does not replace healthchecks with process existence checks
• does not provide deep service orchestration
• does not replace your OS package manager or container runtime
• does not hide a failed required service behind a successful setup task