@wpelevator/tug 0.10.0 → 0.11.0

package/README.md

@@ -1,26 +1,99 @@
 # Tug
 
-The name: tugboats pull ships into place, like the pull-based agents here; `tug` is the CLI.
+Deploy Docker Compose apps to a few ordinary Linux servers, 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).
+You keep your `docker-compose.yml`. Tug installs a small control plane on one server and an agent on each of the others, then `tug deploy` puts your services where you say, waits until they are healthy and rolls back if they are not. It is built for running one to a few dozen sites, WordPress first, on two to ten VPSes, with backups and restores included.
 
-## Features
+## What you can do with it
 
-- 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.
+- **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.
 
-## How it fits together
+Nodes only dial out to the control plane, so they work behind NAT or a firewall that allows nothing inbound. Tug does not need a cloud provider's API, a registry or an overlay network.
+
+## Try it
+
+You need Node.js 22.18 or newer and Docker Compose v2 on your machine, and SSH access to one or more Linux servers (Debian, Ubuntu, Fedora or a RHEL-compatible distribution). Tug can install Docker on them for you.
+
+```bash
+npm install -g @wpelevator/tug      # or run it with npx @wpelevator/tug
+
+tug setup root@203.0.113.5          # install the control plane on a server
+tug node add root@198.51.100.7      # add a server that will run your apps
+tug deploy                          # deploy ./docker-compose.yml
+```
+
+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`
+
+A normal Compose file already works. Add `x-tug` to say where services run, how to tell they are healthy and where traffic comes in:
+
+```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]
+    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
+tug secret set DB_ROOT_PASSWORD
+tug deploy
+tug status       # what is running where, and anything failing
+tug logs wordpress --follow
+```
+
+A complete WordPress site with scheduled database and uploads backups is in the [WordPress example](examples/wordpress/README.md). 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 a handful of Compose apps on VPSes you already pay for, want deploys, rollbacks, secrets and backups handled in one tool, and are happy with a single control server that you back up.
+
+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 (operator credential)
@@ -51,25 +124,11 @@ Deploy Docker Compose applications to one or more ordinary Linux VPSes through a
   SSH is used only by the CLI to install the control plane and nodes.
 ```
 
-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.
-
-## Quick start
-
-Install the CLI (Node >= 22.18), or run it without installing through `npx @wpelevator/tug`:
-
-```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
-```
-
-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.
+`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 any images and pins published images to digests. 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; nodes need just Docker.
 
-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.
+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.
 
-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).
+The full walkthrough, including CI credentials, moving the control plane and recovery, is in [Getting started](docs/getting-started.md).
 
 ## Documentation
 

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)

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

@@ -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.js

@@ -197,7 +197,7 @@ export function createRestoreService(deps) {
             release(restore);
             move(restore, 'failed', { error });
         }
-        event('error', 'restore.failed', restore, `restore of ${restore.target} failed: ${error}${dataChanged ? '; the writers stay held until tug restore-release' : ''}`, { error, held: dataChanged });
+        event('error', 'restore.failed', restore, `restore of ${restore.target} failed: ${error}${dataChanged ? '; the writers stay held until tug restore release' : ''}`, { error, held: dataChanged });
     }
     function queueRestoreJob(restore) {
         const queued = backups.queueRestore(restore.project_id, restore.target, {
@@ -210,72 +210,72 @@ export function createRestoreService(deps) {
         move(restore, 'restoring', { commandId: queued.commandId });
         db.run('UPDATE restore_runs SET node_id=? WHERE id=?', queued.nodeId, restore.id);
     }
+    function advanceHolding(restore, writers, age) {
+        if (!writersReport(restore, writers, 'held')) {
+            if (age > HOLD_TIMEOUT_MS)
+                fail(restore, 'the writers did not stop in time', false);
+            return;
+        }
+        if (!restore.safety_backup)
+            return queueRestoreJob(restore);
+        const safety = backups.runNow(restore.project_id, [restore.target], restore.actor ?? 'restore', 'pre-restore');
+        if (!safety.runs.length)
+            return fail(restore, `the safety backup could not start: ${safety.errors.join('; ')}`, false);
+        move(restore, 'safety_backup', { safetyRunId: safety.runs[0].runId });
+    }
+    function advanceSafetyBackup(restore) {
+        const run = db.get('SELECT * FROM backup_runs WHERE id=?', restore.safety_run_id);
+        if (!run || run.state === 'queued' || run.state === 'running')
+            return;
+        if (run.state === 'succeeded')
+            return queueRestoreJob(restore);
+        fail(restore, `the safety backup ${run.state}${run.error ? ` (${run.error})` : ''}; nothing was changed`, false);
+    }
+    function advanceRestoring(restore, writers) {
+        const command = db.get('SELECT * FROM commands WHERE id=?', restore.command_id);
+        if (!command || ['pending', 'running'].includes(command.state))
+            return;
+        if (command.state !== 'succeeded') {
+            const error = JSON.parse(command.result_json ?? '{}').error ??
+                `the restore command ${command.state}`;
+            return fail(restore, error, restore.mode === 'in-place');
+        }
+        if (restore.mode === 'in-place')
+            release(restore);
+        // The data is back; the restore is done when the services that were stopped are serving again.
+        if (restore.mode === 'in-place' && writers.length)
+            move(restore, 'verifying');
+        else
+            complete(restore);
+    }
+    function advanceVerifying(restore, writers, age) {
+        if (writersReport(restore, writers, 'serving'))
+            return complete(restore);
+        if (age > VERIFY_TIMEOUT_MS)
+            complete(restore, `the data was restored, but ${writers.join(', ')} did not report serving within ${VERIFY_TIMEOUT_MS / MINUTE} minutes; check tug status`);
+    }
+    function advanceRestore(restore) {
+        const age = clock().getTime() -
+            new Date(restore.state_changed_at ?? restore.started_at ?? stamp()).getTime();
+        // Keep the project locked while a restore is unfinished, across a control restart.
+        if (restore.mode === 'in-place' && LOCKED_STATES.includes(restore.state))
+            lock(restore);
+        const writers = JSON.parse(restore.writers_json);
+        switch (restore.state) {
+            case 'holding':
+                return advanceHolding(restore, writers, age);
+            case 'safety_backup':
+                return advanceSafetyBackup(restore);
+            case 'restoring':
+                return advanceRestoring(restore, writers);
+            case 'verifying':
+                return advanceVerifying(restore, writers, age);
+        }
+    }
     /** Advances every restore that is waiting on something; safe to call often. */
     function advance() {
-        for (const restore of db.all(`SELECT * FROM restore_runs WHERE state NOT IN ('succeeded','failed','released')`)) {
-            const age = clock().getTime() -
-                new Date(restore.state_changed_at ?? restore.started_at ?? stamp()).getTime();
-            // Keep the project locked while a restore is unfinished, across a control restart.
-            if (restore.mode === 'in-place' && LOCKED_STATES.includes(restore.state))
-                lock(restore);
-            const writers = JSON.parse(restore.writers_json);
-            switch (restore.state) {
-                case 'holding': {
-                    if (!writersReport(restore, writers, 'held')) {
-                        if (age > HOLD_TIMEOUT_MS)
-                            fail(restore, 'the writers did not stop in time', false);
-                        break;
-                    }
-                    if (!restore.safety_backup) {
-                        queueRestoreJob(restore);
-                        break;
-                    }
-                    const safety = backups.runNow(restore.project_id, [restore.target], restore.actor ?? 'restore', 'pre-restore');
-                    if (!safety.runs.length)
-                        return fail(restore, `the safety backup could not start: ${safety.errors.join('; ')}`, false);
-                    move(restore, 'safety_backup', { safetyRunId: safety.runs[0].runId });
-                    break;
-                }
-                case 'safety_backup': {
-                    const run = db.get('SELECT * FROM backup_runs WHERE id=?', restore.safety_run_id);
-                    if (!run || run.state === 'queued' || run.state === 'running')
-                        break;
-                    if (run.state === 'succeeded')
-                        queueRestoreJob(restore);
-                    else
-                        fail(restore, `the safety backup ${run.state}${run.error ? ` (${run.error})` : ''}; nothing was changed`, false);
-                    break;
-                }
-                case 'restoring': {
-                    const command = db.get('SELECT * FROM commands WHERE id=?', restore.command_id);
-                    if (!command || ['pending', 'running'].includes(command.state))
-                        break;
-                    if (command.state === 'succeeded') {
-                        if (restore.mode === 'in-place')
-                            release(restore);
-                        // The data is back; the restore is done when the services that were stopped are serving again.
-                        if (restore.mode === 'in-place' && writers.length)
-                            move(restore, 'verifying');
-                        else
-                            complete(restore);
-                    }
-                    else {
-                        const error = JSON.parse(command.result_json ?? '{}').error ??
-                            `the restore command ${command.state}`;
-                        fail(restore, error, restore.mode === 'in-place');
-                    }
-                    break;
-                }
-                case 'verifying': {
-                    if (writersReport(restore, writers, 'serving'))
-                        complete(restore);
-                    else if (age > VERIFY_TIMEOUT_MS)
-                        complete(restore, `the data was restored, but ${writers.join(', ')} did not report serving within ${VERIFY_TIMEOUT_MS / MINUTE} minutes; check tug status`);
-                    break;
-                }
-                default:
-            }
-        }
+        for (const restore of db.all(`SELECT * FROM restore_runs WHERE state NOT IN ('succeeded','failed','released')`))
+            advanceRestore(restore);
     }
     function complete(restore, warning) {
         move(restore, 'succeeded', warning ? { error: warning } : {});

package/dist/backup-scheduler.js

@@ -189,7 +189,7 @@ export function createBackupService(deps) {
                 actor,
             });
             if (runId)
-                event('warn', 'backup.no_destination', schedule.project_id, `backup of ${schedule.target} skipped: no backup destination is configured; run tug backup-destination-set`, {
+                event('warn', 'backup.no_destination', schedule.project_id, `backup of ${schedule.target} skipped: no backup destination is configured; run tug backup destination set`, {
                     runId,
                     target: schedule.target,
                 }, null, actor);

package/dist/cli-build.js

@@ -29,7 +29,7 @@ export function sourceArchiveFilter(entry, configPaths, ignores) {
         return false;
     return !compileIgnore(ignores)(relative);
 }
-/** Credential documents written by `control-install --credential-out` (default `tug-root.credential.json`). */
+/** Credential documents, such as the copy `control setup --credential-out` writes (conventionally `*.credential.json`). */
 const CREDENTIAL_FILE = /\.credential\.json$/;
 const ignoreCache = new WeakMap();
 /** Translates one `.dockerignore` pattern: `*`, `?` and `[...]` classes stay within a path segment, `**` crosses them. */

package/dist/cli-config.d.ts

@@ -44,13 +44,18 @@ export declare function localConfigPath(file: string): string;
 export declare function resolveCliConfig(options: ConnectionOptions, env: NodeJS.ProcessEnv, cwd: string, creating?: boolean): Promise<ResolvedCliConfig>;
 /** `nodeDefaults` under the node's own keys; a list in the node replaces the default list. */
 export declare function nodeSettings(config: ResolvedCliConfig, name?: string): SettingValues;
-interface OptionSource {
+interface Named {
     name(): string;
+    parent?: Named | null;
+}
+interface OptionSource extends Named {
     options: readonly {
         attributeName(): string;
     }[];
     getOptionValueSource(key: string): string | undefined;
 }
+/** The space-joined command names from the first subject down, such as `node add`; `setup` is `control setup`. */
+export declare function commandPath(command: Named): string;
 /**
  * Use config values as defaults for the options of a command: a key applies to a command that lists it
  * and has an option of that name, and never over a value given on the command line.

package/dist/cli-config.js

@@ -11,14 +11,7 @@ export const COMMAND_SETTINGS = {
     wait: {
         type: 'boolean',
         flag: '--no-wait',
-        commands: [
-            'deploy',
-            'rollback',
-            'backup-run',
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-        ],
+        commands: ['deploy', 'rollback', 'backup run', 'node add', 'node replace', 'node repair'],
     },
 };
 /** Per-node connection data (`nodes.<name>`); `nodeDefaults` takes the subset that is not node-specific. */
@@ -26,61 +19,32 @@ export const NODE_SETTINGS = {
     ssh: {
         type: 'string',
         flag: '<ssh-target>',
-        commands: ['node-install', 'node-replace-identity', 'node-repair-identity'],
+        commands: ['node add', 'node replace', 'node repair'],
     },
     address: {
         type: 'string',
         flag: '--address',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-register',
-            'node-prepare-enrollment',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node register', 'node enroll'],
     },
     label: {
         type: 'list',
         flag: '--label',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-register',
-            'node-prepare-enrollment',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node register', 'node enroll'],
     },
     installDocker: {
         type: 'boolean',
         flag: '--install-docker',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-            'control-install',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node enroll', 'control setup'],
     },
     image: {
         type: 'string',
         flag: '--image',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-            'control-install',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node enroll', 'control setup'],
     },
     agentControlUrl: {
         type: 'string',
         flag: '--agent-control-url',
-        commands: [
-            'node-install',
-            'node-replace-identity',
-            'node-repair-identity',
-            'node-prepare-enrollment',
-        ],
+        commands: ['node add', 'node replace', 'node repair', 'node enroll'],
     },
 };
 const NODE_SPECIFIC_KEYS = ['ssh', 'address'];
@@ -147,6 +111,16 @@ export async function resolveCliConfig(options, env, cwd, creating = false) {
 export function nodeSettings(config, name) {
     return { ...config.nodeDefaults, ...(name ? config.nodes[name] : undefined) };
 }
+/** Top-level shortcuts that run a grouped command, so config keys and validation treat them alike. */
+const SHORTCUTS = { setup: 'control setup' };
+/** The space-joined command names from the first subject down, such as `node add`; `setup` is `control setup`. */
+export function commandPath(command) {
+    const names = [command.name()];
+    for (let parent = command.parent; parent?.parent; parent = parent.parent)
+        names.unshift(parent.name());
+    const path = names.join(' ');
+    return SHORTCUTS[path] ?? path;
+}
 /**
  * Use config values as defaults for the options of a command: a key applies to a command that lists it
  * and has an option of that name, and never over a value given on the command line.
@@ -154,7 +128,7 @@ export function nodeSettings(config, name) {
 export function applyConfigDefaults(command, values, settings) {
     const attributes = new Set(command.options.map((option) => option.attributeName()));
     for (const [key, value] of Object.entries(settings)) {
-        if (SETTINGS[key]?.commands.includes(command.name()) &&
+        if (SETTINGS[key]?.commands.includes(commandPath(command)) &&
             attributes.has(key) &&
             command.getOptionValueSource(key) !== 'cli')
             values[key] = value;

package/dist/cli-install.d.ts

@@ -8,12 +8,14 @@ export declare function shellQuote(value: unknown): string;
 export declare function dockerRunSnippet(image: string, joinKey: string, address?: string): string;
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export declare function enrollmentCloudInit(bootstrap: string, command: string): string;
-/** Name of the container `control-install` creates (Compose project `tug-control`, service `control`). */
+/** Name of the container `control setup` creates (Compose project `tug-control`, service `control`). */
 export declare const CONTROL_CONTAINER = "tug-control-control-1";
 /** A TCP port is free, or is held by the control container this install would replace, so installing again upgrades in place. */
 export declare function controlPortCheck(port: number): string;
+/** The host of an SSH target: `host`, `user@host`, `ssh://user@host:2222` or bracketed IPv6. */
+export declare function sshHost(sshTarget: string): string;
 /**
- * The default control URL for `control-install`: the SSH target's host and the published port. Accepts
+ * The default control URL for `control setup`: the SSH target's host and the published port. Accepts
  * `host`, `user@host`, `ssh://user@host:2222` and bracketed IPv6. An SSH alias from ~/.ssh/config is used as written,
  * so pass `--control-url` when the alias is not a name or address clients can reach.
  */