Update

2026-07-24 20:29:23 +02:00
commit 66060348da
107 changed files with 14771 additions and 0 deletions
@@ -0,0 +1,112 @@
+# SSH / Unraid deployment
+
+ForgeFlow 0.4 can deploy an exact Gitea commit directly to an Unraid server over SSH.
+
+## Security model
+
+- Enter credentials only in the local ForgeFlow desktop window.
+- Prefer an Ed25519 private key over a password.
+- ForgeFlow stores passwords and private-key passphrases through Electron safe storage.
+- The first successful test records the SSH host-key fingerprint.
+- Later connections fail closed when that fingerprint changes.
+- Diagnostics redact the Gitea token, SSH password and private-key passphrase.
+- ForgeFlow never sends arbitrary commands entered through the renderer. Deployment commands are assembled from validated profile fields.
+
+## Configure the server
+
+Open **Settings → SSH / Unraid servers → Add server**.
+
+Typical Unraid values:
+
+```text
+Name:       Unraid
+Host:       192.168.1.10
+Port:       22
+Username:   root
+Base path:  /mnt/user/appdata
+Auth:       Private key
+```
+
+Save the server, then choose **Test & trust**. ForgeFlow verifies SSH, Git and Docker Compose and records the host-key fingerprint.
+
+## Existing application folder
+
+Create a deployment profile and choose **SSH / Unraid**.
+
+For an existing folder:
+
+```text
+Server folder: lumaops
+Remote path:   /mnt/user/appdata/lumaops
+Compose file:  docker-compose.yml
+```
+
+ForgeFlow inspects the folder before deployment. An existing deployment is adopted only when the project root is a Git working tree. Tracked server-side changes block deployment. Untracked runtime paths such as `.env`, `appdata`, `data`, `logs`, `config` and `compose.override.yml` remain untouched by `git reset --hard`.
+
+Keep the root `.git` directory. It is used to verify the exact commit, update the working tree and roll back to the previous SHA.
+
+Nested Git repositories are reported as warnings and are never removed automatically.
+
+When a Dockerfile is present, preflight also inspects `.dockerignore`. It reports
+whether `.git` is excluded and warns when existing preserved runtime folders or
+nested repositories would still be sent as Docker build context. Fix those
+rules in the repository and commit them rather than changing only the live
+server copy.
+
+## New application folder
+
+For a new project, ForgeFlow creates:
+
+```text
+/mnt/user/appdata/<repository-name>
+```
+
+The Unraid server clones the configured Git URL on the selected branch. The server therefore needs access to that repository, normally through an SSH deploy key or an existing trusted Gitea SSH identity.
+
+Two Compose modes are available:
+
+1. **Use repository Compose file** — recommended for real applications. Keep ports, volumes, devices, networks and Unraid labels version-controlled.
+2. **Generate basic ForgeFlow Compose** — suitable for a simple Dockerfile-based application. ForgeFlow asks for host port, container port, service/container name, Web UI URL and icon URL and writes `.forgeflow/compose.forgeflow.yml`.
+
+Generated Compose deliberately stays minimal. Projects requiring USB devices, GPU access, custom networks, secrets or multiple services should provide their own Compose file.
+
+## Deployment sequence
+
+1. Verify that the local repository is clean, on the allowed branch and fully synchronized with Gitea.
+2. Verify that the exact requested SHA exists on `origin/<branch>`.
+3. Verify the repository Compose file or Dockerfile locally.
+4. Connect through pinned SSH.
+5. Inspect the target folder.
+6. Refuse tracked server-only modifications.
+7. Clone when the folder does not exist.
+8. Fetch the configured branch without allowing interactive credential prompts.
+9. Verify again on the server that the requested full SHA belongs to `origin/<branch>`.
+10. Save the current SHA as the rollback target.
+11. Reset the working tree to the exact requested SHA.
+12. Validate the selected Compose file.
+13. Run `docker compose up -d --build --remove-orphans`.
+14. Store non-secret state under `.forgeflow/` and run the configured healthcheck.
+
+## Folder names
+
+The default folder is the repository name. Existing deployments can keep another folder name by entering it explicitly in the profile. ForgeFlow does not rename populated application folders automatically because Docker paths, scripts and external integrations may depend on them.
+
+A later controlled migration can align names after a successful backup and downtime window.
+
+## Rollback
+
+After a successful deployment, the previous SHA is stored in:
+
+```text
+.forgeflow/previous-sha
+```
+
+Rollback is accepted only for the exact SHA currently recorded as the previous
+deployment. ForgeFlow rechecks that SHA against the configured Gitea branch,
+refuses tracked server-side changes, resets the same working tree, runs Docker
+Compose again and repeats the healthcheck. The version that was live before the
+rollback becomes the new rollback target.
+
+## Before the first real deployment
+
+Back up the application folder and its persistent data. Run **Preflight** and resolve every failed check. Warnings, such as a nested Git repository, should be reviewed but do not automatically delete or modify anything.