64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
.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
|
|
|
|
```text
|
|
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.
|