ForgeFlow/docs/SSH_UNRAID_DEPLOYMENT.md

SSH / Unraid deployment

ForgeFlow uses one deployment flow for Unraid: it copies the exact committed local project from the desktop to the server and activates the Compose definition found for that deployment.

Deployment modes

Direct copy — default

ForgeFlow creates an archive from the exact local commit and uploads it through the configured desktop-to-Unraid connection. Unraid needs Docker, Docker Compose, tar and a SHA-256 checksum tool. Unraid does not clone, fetch or authenticate to a repository.

Monitor only

ForgeFlow inventories and tracks the workload but refuses deploy and rollback operations until Direct copy is selected.

All older SSH/Unraid profiles are migrated to Direct copy unless they were explicitly Monitor only.

Server Inventory and automatic linking

Server Inventory reads the server itself instead of relying on ForgeFlow history. The default scan root is /mnt/user/appdata, together with the configured server base path and the cache-backed appdata path when present. It combines:

• running and stopped containers from docker ps -a and Docker Inspect;
• active and stopped Compose projects;
• DockerMan templates;
• Compose YAML files below the configured appdata roots, including standard override files.

YAML discovery continues even when Docker inspection fails. For each Compose definition ForgeFlow reads the working directory, project name, file set, services and images. It then compares those values with the linked local repositories.

A unique high-confidence match based on both the Compose folder and project identity is linked automatically. Other strong matches show a one-click Link to repository action. The server folder, Compose project, Compose files, service list, visible container identity, ports and preservation paths are already filled in; linking does not recreate the container.

Compose identity

An adopted installation retains the identity detected on the server:

Visible container:        geointel
Server folder:            GeoIntel
Compose project:          geointel
Compose files:            compose.yml, compose.override.yml
Compose services:         web, worker

ForgeFlow adds .forgeflow/compose.metadata.yml as the final Compose overlay. For adopted workloads this overlay adds safe labels only; it does not replace the existing image, volumes, ports, networks or container_name.

--force-recreate and --remove-orphans remain disabled by default. Existing DockerMan templates are not rewritten.

Direct-copy sequence

1. Verify the selected local branch, clean working tree and exact committed HEAD.
2. Test the desktop-to-Unraid connection, Docker, Compose, tar, checksum tooling and deployment storage.
3. Create the release locally with git archive.
4. Upload a temporary .part file through SFTP.
5. Verify SHA-256 and reject unsafe archive paths or symbolic links.
6. Preserve .forgeflow, .git and configured runtime paths such as .env, data, config, logs and application-specific folders.
7. Update only files covered by the managed release manifests; unrelated server files remain untouched.
8. Validate the detected merged Compose configuration.
9. Activate the retained Compose project and verify every selected service is running and not unhealthy.
10. Promote the active SHA and manifests only after activation succeeds.
11. Run the optional desktop health check and persist runtime state.

If activation fails, ForgeFlow restores the previous managed files and Compose metadata and leaves the previous active SHA authoritative.

Authentication model

• The only remote authentication used for Direct copy is the configured desktop-to-Unraid connection.
• That connection may use an Unraid password or a private key.
• Passwords and private-key passphrases use Electron safe storage.
• The first trusted connection records the SSH host-key fingerprint; later changes fail closed.
• Remote inventory collects selected labels, mounts, ports and runtime state; it does not collect container environment values.
• The renderer cannot submit arbitrary shell commands; remote scripts are assembled from validated profile fields.

Rollback

Rollback is allowed only to the exact previousSha recorded for the profile. ForgeFlow recreates that commit archive locally and uses the same upload, checksum, backup, Compose validation and atomic promotion flow.