ForgeFlow/docs/SSH_UNRAID_DEPLOYMENT.md

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:

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:

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:

/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:

.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.