Should self-hosted apps ship a portability manifest?

As a self-hosting admin, I keep running into the gap between “the source is available” and “a normal person can migrate or recover this safely.” A repository rarely tells you, in one dependable place, which database schema and migrations matter, where files actually live, which secrets must be recreated, what background jobs run, or which external services are required.

I’d like every self-hosted application to publish a machine-readable portability manifest: state inventory, secret names (never values), dependencies, backup and restore commands, and a restore procedure tested in a disposable environment. Compose, Helm, OCI metadata, and volume snapshots cover useful pieces, but not the whole operational story.

Should this become a packaging or distribution requirement, at least at a basic lintable level? I worry about imposing real maintenance work on small projects, and about manifests becoming stale paperwork. Could community tools validate them automatically? Share your migration failures, existing standards, or counterarguments.

The standardization case is stronger than the enforcement case. I’m not aware of a broadly adopted format that combines all those fields; existing tools cover narrower slices. A baseline manifest could still be useful if “tested restore” is reported as a dated claim with evidence, rather than treated as a checkbox.

The missing piece is usually ordering. Restore the database, then files, then workers—or the application starts and quietly creates a mess. I’d want the manifest to describe dependencies between steps, not just list commands. A validator could at least detect missing references and run the procedure in a disposable environment.

As a small-project maintainer, I’d resist making this a release gate. The application may have one deployment shape today and five user-specific ones tomorrow. Give projects a tiny schema for declaring known state and a way to say “unknown,” then let distributions add stricter checks if they want.

Strong support for naming secrets without embedding them. A portability document that encourages exporting secret values is a security incident waiting to happen. It should identify required credentials, rotation assumptions, and whether a restore can proceed with newly generated secrets.

This feels like a useful layer above packaging rather than a replacement for it. OCI annotations can point to documentation, Compose can describe mounts and services, and Kubernetes can snapshot volumes, but none establishes application-consistent recovery. A manifest could reference each system instead of duplicating it.

One concern: “portable” can become a misleading product promise. A manifest may pass validation while the destination lacks the right database version, storage class, mail provider, or DNS setup. I’d prefer a declared portability profile with explicit assumptions over a universal green badge.