ForgeFlow/docs/DEPLOYMENT_MIGRATION_EXAMPLE.md

Deployment migration example

This example shows how to bring an existing Git-backed Docker or Unraid application under ForgeFlow control without exposing or overwriting runtime data.

Use synthetic names and values while testing. Replace them with your own repository, server and paths only in ForgeFlow's local configuration; do not commit credentials or environment-specific diagnostics.

1. Establish the authoritative repository

Before deploying, verify that the server checkout and Gitea repository represent the same application:

• compare the complete 40-character commit SHA;
• confirm the configured remote belongs to the intended Gitea origin and repository;
• preserve the root .git directory for exact-SHA verification and rollback;
• resolve any remote URL mismatch explicitly instead of silently rewriting it.

ForgeFlow blocks deployment when the existing origin conflicts with the selected repository unless the user explicitly approves alignment.

2. Protect runtime data

Typical persistent paths include:

.env
appdata/
config/
data/
logs/
compose.override.yml

Keep those paths outside the tracked deployment payload and add runtime-only directories to .dockerignore when they are not build inputs. ForgeFlow uses a controlled Git reset without git clean, but the repository's own Compose and ignore rules remain authoritative.

3. Reuse the maintained Compose definition

Prefer the repository's existing compose.yml or docker-compose.yml when it already defines ports, volumes, device mappings, labels and health checks. These application-specific settings should be reviewed and versioned with the application rather than regenerated during deployment.

4. Handle nested repositories separately

A historical checkout such as source/ may contain another .git directory. Treat this as a migration warning:

1. verify that the root Compose file builds from the intended root;
2. back up the application folder;
3. stop modifying the nested checkout;
4. rename it temporarily;
5. rebuild and verify the application from the root checkout;
6. remove the legacy copy only after rollback has also been tested.

ForgeFlow reports nested repositories but does not delete them automatically.

5. Recommended profile

Provider:       SSH / Unraid
Server folder:  example-app
Branch:         main
Compose mode:   Repository/server Compose
Compose file:   compose.yml
Clone URL:      a Git URL reachable from the server
Healthcheck:    the application's existing health endpoint
Preserve paths: .env, appdata, config, data, logs, compose.override.yml

Complete a preflight first, deploy one exact commit, verify both the live SHA and runtime health, and test rollback before treating the migration as production-ready.