tend/docs/SCHEMA_V2_MIGRATION.md

Schema 1 to schema 2

Schema 2 is intentionally not loaded as schema 1. Keep the installed v0.1 Tend binary available until the first schema-2 activation and rollback have both been exercised.

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.