@wpelevator/tug 0.10.0 → 0.12.0

package/README.md

@@ -1,97 +1,194 @@
 # Tug
 
-The name: tugboats pull ships into place, like the pull-based agents here; `tug` is the CLI.
+Deploy Docker Compose apps to your own Linux VPS, from your laptop or CI, without Kubernetes or a hosted platform.
 
-Deploy Docker Compose applications to one or more ordinary Linux VPSes through a small self-hosted control plane and a pull-based agent on each node, without Kubernetes or a hosted PaaS. Tug runs an agent on each node; the agents drive the node's Docker Engine API directly, and Compose is only used on your machine to read the file. What it is for, the deployment shapes it targets and the planned milestones are in the [Roadmap](docs/roadmap.md).
+A VPS is a durable computer with enough resources to host multiple sites or a medium-size application and its database. Tug helps you use that capacity: keep your Compose file, deploy with one command, and manage rollouts, secrets, backups and restores. Start with one server and add more when you need them. Tug is built for a small number of servers and Compose applications, including Node.js, Laravel, Ruby and WordPress apps.
 
-## Features
+Tug runs a small control plane and an agent, which can share the same VPS with your applications. It builds application images on the control server or your machine and delivers them to your nodes, so you do not need to run or configure an image registry for those builds. Published images are still pulled from their upstream registries.
 
-- One mutual-TLS port: every operator, CI job and node authenticates with a certificate from the control plane's private CA, and control authorizes it by public key. Scoped `read`/`deploy`/`admin` operator credentials for CI and teammates, an audit trail naming who acted, and SQLite metadata through Node's built-in driver.
-- Nodes join over SSH (`node-install`) or enroll themselves with a single `docker run` after `node-prepare-enrollment`, each with its own certificate and an immutable node ID. Agents only dial out, so nodes behind NAT work.
-- Agents pull desired state from control, reconcile containers through the Docker Engine API, run TCP/HTTP/Docker health checks and report status. An outbound WebSocket wakes them as soon as control queues work and carries live `exec`, followed logs, `ps` and `inspect` sessions, with long-poll and periodic-poll fallbacks for ordinary work.
-- `x-tug` placement of services and volumes on nodes, with immutable desired-state records per deployment.
-- Build application images on control from uploaded source, or locally with `deploy --build-local`. Both use a filtered source snapshot that excludes known Tug credentials; operators must still exclude other secrets. Agents download saved images directly from control. Published images are pinned to registry digests at deployment creation.
-- Secrets encrypted at rest, released only to the nodes whose services reference them, with targeted service recreation when only a secret changes.
-- Deployment convergence, per-project operation locks, cancellation, rollback, per-service rollout events and log fetching through the agents.
-- Opt-in zero-downtime rolling rollouts for ingress-fronted services (`x-tug.rollout`) and automatic rollback of failed deployments (`x-tug.rollback: auto`). See [Compose extensions](docs/compose.md#rolling-rollouts).
-- Private published images use encrypted project credentials for digest resolution and Engine API pulls.
-- Health-aware cross-node service names (hosts-file entries injected into containers), on by default with a `TUG_SERVICE_NAMES=false` opt-out, and an optional managed Caddy ingress with automatic HTTPS. Both use each node's private `address` on your existing network. See [Networking](docs/networking.md).
-- Private-by-default published ports: agent-generated container definitions bind them to the node address or loopback, never every interface unless you write `0.0.0.0`. Tug does not encrypt node-to-node workload traffic; your network owns reachability, firewalling and encryption. See [Networking](docs/networking.md#published-ports-private-by-default).
-- Workload backups of service commands and volumes with restic, a separate control-plane backup and restore, and `tug doctor` diagnostics for certificate expiry, node connectivity and clock skew.
-- `tug status --human` summarizes deployments, node reports and failures; the default JSON output remains available for automation.
+## What you can do with it
 
-## How it fits together
+- **Deploy a Compose file to your servers.** `tug deploy` builds or pulls your images, starts them on the right nodes, waits for health checks and tells you why if something fails. `tug rollback` returns to the previous version, and `x-tug: { rollback: auto }` does it for you.
+- **Choose where things run.** Pin a database and its volume to one node, spread web containers over several, and let Tug's managed Caddy ingress serve them over HTTPS with certificates it obtains for you.
+- **Update without downtime.** Opt-in rolling rollouts start the new version, wait until it is healthy and only then switch traffic.
+- **Keep secrets out of your repository.** `tug secret set DB_PASSWORD` stores them encrypted and sends each one only to the nodes whose services use it.
+- **Back up and restore.** Scheduled backups of databases and volumes to S3-compatible storage with restic, and `tug restore run db` to bring one back.
+- **Look inside running services.** `tug logs`, `tug exec`, `tug run` (for example `wp` CLI), `tug ps` and `tug status` work through the control plane, so you never SSH to a node to see what is going on.
+- **Give CI a limited key.** `tug credential create` makes read-only, deploy-only or admin credentials, and every change records who made it.
 
-```text
-  tug CLI / CI (operator credential)
-       |
-       |  mTLS: deploy, status, logs, exec
-       v
-+-------------------------------------+
-| Control plane (one mTLS port)       |
-|   Control API (role-checked)        |
-|   SQLite: desired states, secrets   |
-|   private CA, image builds          |
-+-------------------------------------+
-       ^                       ^
-       |  agents dial out: work, status,
-       |  WebSocket wake and live sessions
-       |                       |
-+------+------------+   +------+------------------+
-| Node app1         |   | Node app2 (ingress node)|
-|   Agent           |   |   Agent                 |
-|   Docker Engine   |   |   Docker Engine         |
-|   services        |   |   services              |
-|                   |   |   managed Caddy ingress |
-+-------------------+   +-------------------------+
-        \_________________________/
-          workload traffic between node addresses
-          over the operator's private network
-
-  SSH is used only by the CLI to install the control plane and nodes.
-```
+Agents only dial out to the control plane, so nodes can work behind NAT or a firewall that allows nothing inbound. Tug does not need a cloud provider's API or an overlay network.
+
+## Try it
 
-Operators and CI talk to the control API. The control plane stores desired state and builds images; each agent dials out to fetch the work for its node, applies it through the Docker Engine API and reports health back, so the control channel works through NAT without inbound ports. SSH is used only to install the control plane and its nodes. Cross-node service names and Caddy ingress use each node's `address` over the operator's private network; Tug provides no overlay or encryption for that workload traffic. See [Networking](docs/networking.md), and [Architecture](docs/architecture.md) for every flow in detail.
+Follow [Deploy your first service](docs/getting-started.md) to install Tug, deploy nginx to one VPS and verify that it works. You need Node.js 22.18 or newer and Docker Compose v2 on your computer, plus SSH access to a Linux server. Tug can install Docker on supported servers.
+
+```bash
+npm install -g @wpelevator/tug      # or run it with npx @wpelevator/tug
 
-## Quick start
+tug setup root@203.0.113.5          # install the control plane
+tug node add root@203.0.113.5 --name app1  # install the agent on the same VPS
+tug deploy                          # deploy a Compose file in this directory
+```
 
-Install the CLI (Node >= 22.18), or run it without installing through `npx @wpelevator/tug`:
+The control plane and agent share the VPS with your application. Once your service is running, you can [add HTTPS](docs/networking.md#layer-b-ingress-and-tls), [back up your data](docs/backups.md) or [add another server](docs/service-placement.md).
+
+In a terminal Tug asks before it changes anything: whether to install Docker, which private address the node should use and whether it should handle ingress. It shows the plan and waits for you to confirm. `tug deploy` asks for any Compose variables, such as `${DB_PASSWORD}`, that no secret or `.env` provides. In CI or any other script nothing is ever asked, so pass the choices as flags (`--address`, `--ingress`, `--install-docker`, `-y`).
+
+## Your Compose file, plus a little `x-tug`
+
+This example builds on the [quickstart](docs/getting-started.md). It pins the app, database and database volume to `app1`. Placement can be omitted with one node, but explicit placement keeps the database on its chosen server when you add more nodes. Enable ingress with `tug node ingress app1`, point the hostname's DNS at the VPS, and allow public ports 80 and 443. Save this as `compose.yaml` and replace the hostname with yours:
+
+```yaml
+services:
+  db:
+    image: mariadb:11.4.8
+    volumes:
+      - db-data:/var/lib/mysql
+    environment:
+      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
+    x-tug:
+      placement:
+        nodes:
+          - app1
+      health:
+        type: tcp
+        port: 3306
+
+  wordpress:
+    image: wordpress:6.8.3-apache
+    depends_on:
+      - db
+    environment:
+      WORDPRESS_DB_HOST: db
+      WORDPRESS_DB_USER: root
+      WORDPRESS_DB_PASSWORD: ${DB_ROOT_PASSWORD}
+    ports:
+      - "8080:80"
+    x-tug:
+      placement:
+        nodes:
+          - app1
+      health:
+        type: http
+        port: 80
+        path: /wp-includes/version.php
+      ingress:
+        host: blog.example.com
+        port: 80
+        tls: auto
+
+volumes:
+  db-data:
+    x-tug:
+      placement:
+        nodes:
+          - app1
+```
 
 ```bash
-npm install -g @wpelevator/tug
-tug control-install root@203.0.113.5 --install-docker
-tug init tug-root.credential.json
-tug node-install root@198.51.100.7 --name app1 --address 10.0.0.7 --install-docker
-tug deploy -f docker-compose.yml
+tug secret set DB_ROOT_PASSWORD
+tug deploy
+tug status       # what is running where, and anything failing
+tug logs wordpress --follow
 ```
 
-The CLI installs the matching `ghcr.io/wpelevator/tug:<version>` image on your hosts. Control serves mutual TLS directly on its port (`8443`): every operator, CI job and node authenticates with a certificate from a private CA created at install, and clients verify a name generated from that CA, so the address can be a bare IP and can change later. Do not terminate TLS in front of it.
+The named volume holds data on `app1`; it is not copied to another node automatically. Back it up and restore or move its data deliberately if you replace the server.
+
+See the [examples directory](examples/) for stack-specific applications. Everything `x-tug` can express is in [Compose extensions](docs/compose.md).
+
+## Everyday commands
+
+Project commands sit at the top level; everything else reads `tug <subject> <verb>`.
+
+| I want to... | Run |
+| --- | --- |
+| Deploy, or undo a deploy | `tug deploy`, `tug rollback` |
+| See what is running and what failed | `tug status`, `tug events`, `tug ps` |
+| Read logs or open a shell | `tug logs <service>`, `tug exec <service> sh` |
+| Run a one-off command | `tug run <service> -- wp cache flush` |
+| Change the number of replicas | `tug scale <service> 3` |
+| Add, list or replace servers | `tug node add`, `tug node list`, `tug node replace <name>` |
+| Add a server I cannot SSH to | `tug node enroll`, then run the printed `docker run` on it |
+| Manage secrets | `tug secret set`, `tug secret list`, `tug secret remove` |
+| Back up now, or restore | `tug backup run`, `tug restore run <target>` |
+| Give CI a deploy key | `tug credential create ci --role deploy` |
+| Check everything is healthy | `tug doctor` |
+
+Every command and option is in the [CLI reference](docs/cli.md). `tug status --json` prints raw JSON for scripts.
+
+## Is Tug right for you?
+
+Tug fits if you run Compose apps on one or a few VPSes, want deploys, rollbacks, secrets and backups handled in one tool, and are happy with a single control server that you back up. A server can host multiple apps as long as it has enough capacity; Tug does not automatically balance resource usage or replace a failed server.
+
+It deliberately does not do Kubernetes-style scheduling, autoscaling, distributed storage or database failover, and it does not provision servers through a provider's API. Node-to-node traffic travels over your own private network (Tailscale, a VPC, a LAN), so you own its firewalling and encryption. If you want automatic rescheduling of containers across a cluster, see how it compares with [Docker Swarm](docs/swarm-comparison.md). The goals, principles and planned milestones are in the [Roadmap](docs/roadmap.md).
+
+## How it works
+
+```text
+                      tug CLI / CI
+                           |
+                           | mTLS: deploy, status, logs, exec
+                           v
++--------------------------------+     +--------------------------------+
+| VPS app1                       |     | VPS app2 (optional)            |
+|                                |     |                                |
+| Control plane                  |     |                                |
+| API, SQLite, image builds      |     |                                |
+|                                |     |                                |
+| Agent --> Docker Engine        |     | Agent --> Docker Engine        |
+|              |                 |     |              |                 |
+|              +-- service A     |     |              +-- service C     |
+|              +-- database      |     |              +-- service D     |
+|              +-- more...       |     |              +-- more...       |
+|     (zero or more services)    |     |     (zero or more services)    |
+|                                |     |                                |
+| Local volumes, optional Caddy  |     | Local volumes, optional Caddy  |
++--------------------------------+     +--------------------------------+
+             |                                         |
+             +------- private workload network --------+
+
+  Each agent connects to the control plane over mTLS. Services are
+  placed on either node; local volumes stay on their node. app1 can
+  run alone. SSH installs control and agents; normal operations use
+  the control API.
+```
 
-A `controlUrl` in `tug.yml` is the one name for where control is: `control-install` advertises it, and every other command connects to it. Pass `--control-url` (or set `TUG_CONTROL_URL`) to override it for one invocation. See [CLI configuration](docs/cli.md#config-file) for precedence and per-node defaults.
+`tug deploy` reads your Compose file on your machine and sends it to the control plane, which stores it as an immutable desired state, builds application images when needed and pins published images to digests. Tug delivers its built images as archives; published images are pulled from their upstream registries. Each agent fetches the work for its node, applies it through the Docker Engine API, runs the health checks and reports back. The control plane marks the deployment done when every node reports it serving. Compose runs only on your machine for application normalization; nodes need Docker, and the control installation also uses Compose. Cross-node workload traffic uses your own private network.
 
-The full walkthrough, including nodes you cannot SSH to (`tug node-prepare-enrollment`), CI credentials (`tug credential-create`), moving the control plane and recovery, is in [Getting started](docs/getting-started.md).
+Control serves mutual TLS directly on one port (`8443`). Every operator, CI job and node authenticates with a certificate from a private CA created at install, so the control address can be a bare IP and can change later. Do not terminate TLS in front of it. A `controlUrl` in `tug.yml` tells the CLI where control is (see [CLI configuration](docs/cli.md#config-file)). [Architecture](docs/architecture.md) covers every flow in detail, and [Security](docs/security.md) the trust boundaries.
 
 ## Documentation
 
-- [Getting started](docs/getting-started.md): install control, add nodes, deploy, give CI a credential, move control, recover.
-- [Terminology](docs/terminology.md): core concepts, the naming review (which recommendations are implemented), industry comparisons and the remaining proposed interface improvements.
-- [Architecture](docs/architecture.md): components, reconciliation, workflow diagrams, secrets and runtime paths.
-- [Compose extensions](docs/compose.md): `x-tug` placement, health checks, volumes and limitations.
-- [Control plane](docs/control-plane.md): install, mutual TLS and the private CA, image delivery, control-plane backup and recovery on another host.
-- [Backups](docs/backups.md): scheduled workload backups with `x-tug.backup` (restic), restore, recipes for common databases, and a restore drill. See also the [WordPress example](examples/wordpress/README.md).
-- [Access control](docs/access-control.md): certificate identity classes, scoped operator credentials, roles, audit trail and a GitHub Actions deploy example.
-- [Security](docs/security.md): deployment trust boundaries, security audit findings and validation limits.
-- [Networking](docs/networking.md): bring-your-own private networking, cross-node service names, ingress and TLS, firewall notes.
-- [Nodes](docs/nodes.md): node names and IDs, SSH install, self-service enrollment, certificate renewal and recovery, registration and status.
-- [CLI reference](docs/cli.md): every `tug` command and option.
-- [Configuration](docs/configuration.md): CLI, control and agent environment variables.
-- [Development](docs/development.md): local setup, CI, Compose stack, host mode and the integration test.
-- [Testing](docs/testing.md): test layers, rollout metrics, mocked test backlog, and the [Caddy/PHP and static-file benchmark](docs/testing.md#caddy-proxy-overhead-benchmark).
-- [Observability](docs/observability.md): what can be observed today, and the proposed logs, metrics and alerting.
-- [Releases](docs/releases.md): changesets, npm and Docker image publishing.
-- [Standalone binary](docs/standalone-binary.md): proposed Bun-compiled CLI binaries and Homebrew distribution, with the mTLS dependency findings.
-- [Roadmap](docs/roadmap.md): goals, principles, the reference WordPress topology and planned milestones.
-- [Docker Swarm comparison](docs/swarm-comparison.md): overlapping capabilities, workflow advantages, scheduling and networking limits, failure behavior and workload fit.
+Start with the [single-VPS tutorial](docs/getting-started.md), then choose the topic that matches your next task:
+
+- **Deploy and operate**
+  - [Application examples](examples/README.md)
+  - [Health checks and rollouts](docs/healthchecks.md)
+  - [Troubleshooting](docs/troubleshooting.md)
+- **Networking and access**
+  - [Hostnames, HTTPS and service networking](docs/networking.md)
+  - [Credentials and CI](docs/access-control.md)
+  - [Security trust boundaries](docs/security.md)
+- **Servers and data**
+  - [Service placement and scaling](docs/service-placement.md)
+  - [Node management](docs/nodes.md)
+  - [Backups and recovery](docs/backups.md)
+  - [Moving to new servers](docs/migration.md)
+- **Reference**
+  - [CLI](docs/cli.md)
+  - [Compose extensions](docs/compose.md)
+  - [Configuration](docs/configuration.md)
+  - [Control plane](docs/control-plane.md)
+- **Contribute and design**
+  - [Development](docs/development.md)
+  - [Testing](docs/testing.md)
+  - [Releases](docs/releases.md)
+  - [Architecture](docs/architecture.md)
+  - [Roadmap](docs/roadmap.md)
+  - [Observability status and proposal](docs/observability.md)
+  - [Terminology](docs/terminology.md)
+  - [Standalone binary proposal](docs/standalone-binary.md)
+  - [Docker Swarm comparison](docs/swarm-comparison.md)
 
 ## Development
 

package/dist/agent-credential.js

@@ -5,7 +5,7 @@ import { Agent, fetch as undiciFetch } from 'undici';
 import { clientTlsOptions, createCsr, generateKeyPair, identityUri, parseCredential, validateInstalledCertificate, writeFileDurable, } from "./pki.js";
 export const agentFile = (stateDir) => path.join(stateDir, 'agent.json');
 export const pendingFile = (stateDir) => path.join(stateDir, 'agent-pending.json');
-const NO_AGENT_IDENTITY = 'this node has no identity: run `tug node-install`, `tug node-prepare-enrollment` or `tug node-repair-identity` from an operator machine';
+const NO_AGENT_IDENTITY = 'this node has no identity: run `tug node add`, `tug node enroll` or `tug node repair` from an operator machine';
 async function readJson(file) {
     let text;
     try {
@@ -20,7 +20,7 @@ async function readJson(file) {
         return JSON.parse(text);
     }
     catch (e) {
-        throw new Error(`${file} is corrupt; run \`tug node-repair-identity\` to replace this node's identity`, {
+        throw new Error(`${file} is corrupt; run \`tug node repair\` to replace this node's identity`, {
             cause: e,
         });
     }
@@ -37,7 +37,7 @@ export async function loadAgentDocument(stateDir) {
         return { ...credential, nodeId, nodeName };
     }
     catch (e) {
-        throw new Error(`${agentFile(stateDir)} is invalid (${e instanceof Error ? e.message : String(e)}); run \`tug node-repair-identity\``, { cause: e });
+        throw new Error(`${agentFile(stateDir)} is invalid (${e instanceof Error ? e.message : String(e)}); run \`tug node repair\``, { cause: e });
     }
 }
 async function pendingKey(stateDir) {

package/dist/agent.js

@@ -500,7 +500,7 @@ export function runsInContainer() {
 export function outsideContainerHint(health, inContainer = runsInContainer()) {
     if (inContainer || health.type === 'docker')
         return '';
-    return '; this agent is not running in a container, so it may be unable to reach container addresses (a host process on macOS cannot); run it with `docker run` as `tug node-install` does';
+    return '; this agent is not running in a container, so it may be unable to reach container addresses (a host process on macOS cannot); run it with `docker run` as `tug node add` does';
 }
 export async function waitForHealth(ctx, project, container, service, health) {
     if (!ctx.apply || !health)
@@ -518,9 +518,11 @@ export async function waitForHealth(ctx, project, container, service, health) {
                     throw new Error(`${service}: docker health ${state.Health.Status}`);
             }
             else if (health.type === 'tcp') {
+                await assertRunning(ctx, container, service);
                 await tcpCheck(await containerIp(ctx, project, container), health.port, parseDuration(health.timeout || '2s'));
             }
             else if (health.type === 'http') {
+                await assertRunning(ctx, container, service);
                 const ip = await containerIp(ctx, project, container);
                 const res = await ctx.http(`http://${ip}:${health.port || 80}${health.path || '/'}`, {
                     signal: AbortSignal.timeout(parseDuration(health.timeout || '2s')),
@@ -537,6 +539,33 @@ export async function waitForHealth(ctx, project, container, service, health) {
     }
     throw new Error(`${service}: ${describeHealthCheck(health)} failed after ${retries} attempt${retries === 1 ? '' : 's'}: ${describeError(last)}${outsideContainerHint(health)}`);
 }
+/** Fails fast with the exit code and last log lines when the container is gone, instead of dialing a dead address. */
+async function assertRunning(ctx, container, service) {
+    const state = (await ctx.docker.inspectContainer(container)).State;
+    if (!state || state.Running)
+        return;
+    const tail = await lastLogLines(ctx, container);
+    throw new Error(`${service}: container exited with code ${state.ExitCode ?? '?'}${tail ? `; last log: ${tail}` : ''}`);
+}
+async function lastLogLines(ctx, container, lines = 3) {
+    try {
+        const proc = await ctx.docker.logs(container, { follow: false, tail: lines });
+        let out = '';
+        const collect = (chunk) => void (out += chunk.toString());
+        proc.stdout.on('data', collect);
+        proc.stderr.on('data', collect);
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, 2000);
+            proc.stdout.once('close', () => (clearTimeout(timer), resolve()));
+            proc.stdout.once('end', () => (clearTimeout(timer), resolve()));
+        });
+        proc.kill();
+        return out.trim().split('\n').slice(-lines).join(' | ').slice(0, 400);
+    }
+    catch {
+        return '';
+    }
+}
 /** Node's fetch reports every network failure as "fetch failed"; the system error that explains it is on `cause`. */
 function describeError(error) {
     const e = error;
@@ -987,8 +1016,10 @@ export async function reconcile(desiredState, ctx = defaultContext(), endpoints
                 markEvents('failed');
             }
             // Rolling services are untouched by a failure here, so keep reporting their current revision as serving.
-            if (!rolling.length)
-                throw e;
+            if (!rolling.length) {
+                // Callers turn the throw into a failed status; carry the per-service states so a held writer is still seen.
+                throw Object.assign(e instanceof Error ? e : new Error(errMessage(e)), { serviceStates });
+            }
             Object.assign(serviceStates, await activeRollingStates(dir, rolling));
             return failedStatus(errMessage(e));
         }
@@ -1099,6 +1130,11 @@ export async function pollOnce(ctx = defaultContext()) {
                 ...(desired.revision ? { observedRevision: desired.revision } : {}),
                 health: 'failed',
                 error: errMessage(e),
+                ...(e.serviceStates
+                    ? {
+                        serviceStates: e.serviceStates,
+                    }
+                    : {}),
             });
         }
     }

package/dist/backup-check.d.ts

@@ -1,4 +1,4 @@
-/** The part of `GET /api/v1/backups` that `tug backup-list --check` judges. */
+/** The part of `GET /api/v1/backups` that `tug backup list --check` judges. */
 export interface BackupCheckInput {
     destinationConfigured: boolean;
     targets: {

package/dist/backup-config.js

@@ -145,7 +145,7 @@ export function resolveBackups(compose, project = '') {
                 ? defaultSchedule.trim()
                 : undefined;
         if (spec.schedule === undefined && schedule === undefined)
-            errors.push(`${label} needs a schedule: set ${label}.schedule or x-tug.backup.schedule`);
+            errors.push(`${label} needs a schedule: set ${label}.schedule or a project-level schedule at the top-level x-tug.backup.schedule`);
         const retention = spec.retention !== undefined
             ? validateRetention(label, spec.retention, errors)
             : defaultRetention;
@@ -184,18 +184,25 @@ export function resolveBackups(compose, project = '') {
             return null;
         return { schedule, retention, jitterSeconds, timeoutSec, memory };
     };
-    for (const [name, svc] of Object.entries(compose.services)) {
-        const config = svc['x-tug']?.backup;
-        if (config === undefined)
-            continue;
-        const label = `${name}: x-tug.backup`;
+    /** The object form of a backup config; null when it is off, or invalid (the error is reported). */
+    const specOf = (label, config) => {
         const spec = normalizeConfig(config);
         if (spec === null)
-            continue;
+            return null;
         if (typeof spec !== 'object' || Array.isArray(spec)) {
             errors.push(`${label} must be true, false, a cron string or an object`);
-            continue;
+            return null;
         }
+        return spec;
+    };
+    const serviceTarget = (name, svc) => {
+        const config = svc['x-tug']?.backup;
+        if (config === undefined)
+            return null;
+        const label = `${name}: x-tug.backup`;
+        const spec = specOf(label, config);
+        if (!spec)
+            return null;
         const before = errors.length;
         const base = common(label, 'service', name, spec);
         const argv = spec.command === undefined ? null : commandArgv(spec.command);
@@ -216,8 +223,8 @@ export function resolveBackups(compose, project = '') {
         if (global || replicas > 1 || nodes.length > 1)
             errors.push(`${label} needs a single instance; ${name} is global, replicated or placed on several nodes`);
         if (errors.length > before || !base || !argv)
-            continue;
-        targets.push({
+            return null;
+        return {
             target: `service:${name}`,
             kind: 'service',
             name,
@@ -229,20 +236,16 @@ export function resolveBackups(compose, project = '') {
             verify: spec.verify,
             writers: spec.writers,
             node: !dynamic && nodes.length === 1 ? nodes[0] : undefined,
-        });
-    }
-    for (const [name, def] of Object.entries(compose.volumes || {})) {
+        };
+    };
+    const volumeTarget = (name, def) => {
         const config = isObject(def) ? def['x-tug']?.backup : undefined;
         if (config === undefined)
-            continue;
+            return null;
         const label = `volumes.${name}: x-tug.backup`;
-        const spec = normalizeConfig(config);
-        if (spec === null)
-            continue;
-        if (typeof spec !== 'object' || Array.isArray(spec)) {
-            errors.push(`${label} must be true, false, a cron string or an object`);
-            continue;
-        }
+        const spec = specOf(label, config);
+        if (!spec)
+            return null;
         const before = errors.length;
         const base = common(label, 'volume', name, spec);
         if (spec.exclude !== undefined &&
@@ -260,8 +263,8 @@ export function resolveBackups(compose, project = '') {
         else if (!placed.length && dynamicPlacement)
             errors.push(`${label} needs x-tug.placement.nodes on volume ${name}, since its services are placed by label or global`);
         if (errors.length > before || !base)
-            continue;
-        targets.push({
+            return null;
+        return {
             target: `volume:${name}`,
             kind: 'volume',
             name,
@@ -270,7 +273,12 @@ export function resolveBackups(compose, project = '') {
             exclude: spec.exclude,
             writers: spec.writers,
             node: candidates.length === 1 ? candidates[0] : undefined,
-        });
-    }
+        };
+    };
+    const found = [
+        ...Object.entries(compose.services).map(([name, svc]) => serviceTarget(name, svc)),
+        ...Object.entries(compose.volumes || {}).map(([name, def]) => volumeTarget(name, def)),
+    ];
+    targets.push(...found.filter((target) => target !== null));
     return { targets, errors };
 }

package/dist/backup-destination.d.ts

@@ -15,7 +15,7 @@ export declare function projectRepository(destinationUrl: string, project: strin
 /**
  * The repository password of a project, derived from the control master key so nothing extra is stored and
  * a node only ever holds the passwords of projects it runs backups for. Losing the master key loses every
- * repository, which is why `tug backup-repository-password` exists for offline escrow.
+ * repository, which is why `tug backup password` exists for offline escrow.
  */
 export declare function repositoryPassword(masterKey: string, project: string): string;
 /** Removes every known secret value from text that is about to be stored, shown or put in an event. */

package/dist/backup-destination.js

@@ -54,7 +54,7 @@ export function projectRepository(destinationUrl, project) {
 /**
  * The repository password of a project, derived from the control master key so nothing extra is stored and
  * a node only ever holds the passwords of projects it runs backups for. Losing the master key loses every
- * repository, which is why `tug backup-repository-password` exists for offline escrow.
+ * repository, which is why `tug backup password` exists for offline escrow.
  */
 export function repositoryPassword(masterKey, project) {
     return createHmac('sha256', masterKey).update(`tug-restic:${project}`).digest('hex');

package/dist/backup-restore.d.ts

@@ -31,7 +31,14 @@ export interface RestoreDeps {
     clock?: () => Date;
 }
 /**
- * The services that write to a target. For a service they are the services that depend on it, transitively;
+ * True when an environment entry points at `service` over the network: a host-like variable that is exactly the
+ * service name (`WORDPRESS_DB_HOST=db`), or a value that names it as a host (`db:3306`, `mysql://u:p@db/app`,
+ * `mysql:host=db;dbname=app`). A service reached across nodes has no `depends_on` to find it by.
+ */
+export declare function environmentReaches(service: string, key: string, value: string): boolean;
+/**
+ * The services that write to a target. For a service they are the services that depend on it, transitively,
+ * plus the services whose environment names it as a host, which is how a service on another node reaches it (only for the target itself, not for what depends on the writers);
  * for a volume, the services that mount it and everything depending on those. Stored `depends_on` is used,
  * because the per-node copies drop cross-node dependencies.
  */