tend/docs/SCHEMA_V2_MIGRATION.md

Schema 1 to schema 2

Configuration schema 2 and deployment state are separate versioned contracts. The service configuration moves to schema 2, while conventional deployment state deliberately remains schema 1 so the retained v0.1 binary can still read active and previous release identities during recovery.

Singleton operations write an adjacent, strict <state-file>.candidate-lease.json file containing the operation, release, unit, address, and start time. Older binaries ignore that additive file. Do not downgrade or start another deployment while a lease is present: first use the new binary's tend reconcile --json report to establish which process and route are healthy. Tend does not silently invent a lease for a legacy interrupted operation.

1. Move each configuration to /etc/tend/services/<service>.json.
2. Set schema_version to 2.
3. Add service.environment_file below /etc/tend/environment/.
4. Create that file as a regular root-owned file with mode 0600. Move secret values out of JSON. Do not put the environment file in Git. For a singleton, keep its listen_env key out of this shared file: set the live address in the installed unit and let Tend supply only the candidate address.
5. Set every service's deployment.lock_file to /run/lock/tend-deploy.lock.
6. Add one or more query-free HTTPS deployment.public_smoke checks.
7. Add a per-service deployment.event_log below its release root and a bounded deployment.activation_window_seconds value. Keep the log root-owned and grant collectors read access explicitly.
8. For singleton services, add the full Caddy configuration, imported handler, and one-upstream handler-template paths. The template must be reviewed and contain exactly one {{UPSTREAM}} marker so Tend can keep traffic on the candidate while the fixed-address unit restarts.
9. Update installed systemd units to read the same environment file as the transient candidate.
10. Install a root-owned 0600 receive policy mapping each service name to its exact configuration and artifact-size ceiling.
11. Run tend check-server as root before accepting a transfer.
12. Validate, activate, rollback, and reactivate one service at a time. Confirm unrelated services never restart.

Tend does not discover .env, infer old values, rewrite a production file, or silently migrate state. For local development, copy a committed .env.example to an ignored .env.local, restrict its mode, and load it with the application's own tooling. Tend never loads local dotenv files implicitly.