ForgeFlow/docs/SSH_UNRAID_DEPLOYMENT.md

SSH / Unraid deployment

ForgeFlow can inventory existing Unraid workloads and deploy an exact Git commit through one of three explicit modes.

Deployment modes

Push bundle — default

ForgeFlow creates an archive from the exact local commit and uploads it through the trusted desktop-to-Unraid SSH connection. The Unraid server needs Docker, Docker Compose, tar and a SHA-256 checksum tool. It does not need Git access or a Gitea key.

Server-side Git — optional

Unraid fetches the exact commit from Gitea. This mode additionally requires Git, a trusted Gitea host key and a non-interactive Unraid-to-Gitea identity with repository access.

Monitor only

ForgeFlow inventories and tracks the workload but refuses deploy and rollback operations until another mode is selected.

Security model

• Credentials are entered only in the local ForgeFlow desktop application.
• Ed25519 private keys are preferred.
• Passwords and key passphrases use Electron safe storage.
• The first trusted connection records the SSH host-key fingerprint; later changes fail closed.
• ForgeFlow validates the selected private key before saving the server configuration.
• Desktop-to-Unraid authentication, Docker access, Compose availability and optional Unraid-to-Gitea access are reported as separate checks.
• 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 and transported as base64-encoded Bash input.
• Incomplete SSH output is rejected rather than interpreted.

Server Inventory and manual linking

Server Inventory includes running and stopped containers, Compose projects, DockerMan installations and standalone containers even when /mnt/user/appdata/<app> is not a Git checkout.

An exact repository remote or trusted provenance label may be linked automatically. Similar names remain suggestions. For an uncertain workload, use Link workload and choose:

1. the repository;
2. Push bundle, Server-side Git or Monitor only;
3. the folder below the configured server base path.

The resulting profile preserves the detected Compose project name, Compose files, service set, container metadata and stable workload selector. Linking itself does not recreate a container or rewrite a DockerMan template.

Compose identity

An adopted installation keeps the identity reported by Docker:

Visible container:        omniroute
Server folder:            OmniRoute
Compose project:          omniroute-production
Compose files:            compose.yml, compose.unraid.yml
Compose services:         api, worker

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

--force-recreate and --remove-orphans are disabled by default and can be enabled explicitly per profile. Multiple Compose files and services are retained and validated.

DockerMan safety

Existing DockerMan templates under /boot/config/plugins/dockerMan/templates-user are never rewritten for adopted workloads. ForgeFlow manages a persistent DockerMan template only when all of the following are true:

• the profile uses ForgeFlow-generated Compose;
• Manage DockerMan template is enabled;
• the workload was not adopted from the server.

Metadata repair for an adopted application therefore updates the Compose metadata labels only and leaves the original Unraid template intact.

Push bundle sequence

1. Verify the clean local working tree, selected branch, upstream state and exact commit.
2. Verify the exact commit exists on the configured remote branch.
3. Test desktop-to-Unraid SSH, Docker, Compose, tar, checksum tooling and deployment storage.
4. Create the release with git archive from the exact commit.
5. Upload a temporary .part file through SFTP.
6. Verify the SHA-256 digest and reject unsafe paths or symbolic links.
7. Store a retained release manifest and back up files that ForgeFlow is about to manage.
8. Preserve .forgeflow, .git and configured runtime paths such as .env, data, config, logs and application-specific folders.
9. Update only files in the old or new ForgeFlow managed-file manifests; unrelated server files remain untouched.
10. Validate the merged Compose configuration.
11. Start the configured Compose project and verify every selected service has a running container and is not unhealthy.
12. Promote current-sha, status and managed-file manifests atomically.
13. Run the optional desktop healthcheck and persist runtime state.

If activation fails, ForgeFlow restores the backed-up files and previous Compose metadata, restarts the previous Compose state where possible and leaves the previous active SHA untouched.

Server-side Git sequence

Server-side Git retains the exact-SHA flow for installations that deliberately keep a checkout on Unraid. Preflight runs git ls-remote from Unraid, rejects tracked server edits, verifies the configured origin and checks that the selected SHA belongs to the allowed remote branch. The active SHA is written only after Compose validation and service verification.

Interrupted operations and locks

A push deployment creates .forgeflow/deploy.lock with a request ID, timestamp and shell PID. A lock older than two hours is removed only when its recorded process no longer exists. Startup and Reconcile compare the requested SHA with server state and container health; unresolved operations eventually become failed rather than remaining active indefinitely.

Rollback

Rollback is accepted only for the exact previousSha recorded for the profile. Push bundle mode recreates that commit archive locally and uses the same checksum, backup, Compose validation and atomic promotion flow. Server-side Git mode verifies and checks out the exact previous commit through its Git workflow.