ForgeFlow/docs/LUMAOPS_SERVER_AUDIT.md

LumaOps server versus Gitea audit

This audit compares the supplied lumaops_server.zip and LumaOps_gitea.zip.

Main result

The main Unraid working tree and the supplied Gitea checkout point to exactly the same commit:

d42d4a7f08240c478d07466e3fabec654dc71367

Latest subject:

Preserve colors across Aura zone updates

There is therefore no source-version drift at the root of the live LumaOps folder.

Root Git repository

The root .git directory should remain in place. It enables:

• exact-SHA verification;
• controlled fetch and reset;
• a reliable previous-version reference;
• rollback without copying a second complete source tree.

The archived server copy showed one root status difference for scripts/unraid-hardware-setup.sh: file mode 100755 → 100644. This is consistent with Unix executable bits being lost during ZIP handling. The file content did not differ. Check the executable bit directly on Unraid before deployment.

Origin URL mismatch to resolve

The supplied server root uses:

ssh://git@127.0.0.1:222/NuklearRabbit/LumaOps.git

The supplied Gitea checkout uses:

https://gitea.itworx.tech/Jens/LumaOps.git

Although both archives currently point to the same commit, these are different repository paths. Before the first ForgeFlow deployment, choose the server- reachable URL for the authoritative Jens/LumaOps repository, for example an SSH URL through 127.0.0.1:222 when Gitea runs on the same Unraid host.

ForgeFlow 0.4 detects this mismatch. Deployment is blocked unless the profile matches the existing origin or Align an existing server origin to this URL is explicitly enabled.

Runtime and persistent paths

The server copy contains runtime data that must not be replaced by source updates:

• appdata/
• data/
• logs/
• .env and application-specific configuration

The repository .gitignore already excludes the principal runtime paths. ForgeFlow's SSH strategy uses Git reset without git clean, so untracked persistent data remains in place.

Compose and Unraid integration

The root docker-compose.yml is already suitable as the authoritative deployment definition. It includes:

• build context at the project root;
• container name lumaops;
• the Unraid dockerman label;
• a Web UI label;
• an Unraid icon label;
• ${WEB_PORT:-1223}:${APP_PORT:-8080};
• persistent relative volumes;
• USB, HID and I²C devices;
• a healthcheck.

ForgeFlow should use this existing Compose file rather than generate a replacement. Ports and complex device mappings belong in the repository's maintained Compose definition.

The supplied .dockerignore already excludes .git, so keeping the root Git working tree does not copy Git history into the Docker build context. It does not yet explicitly exclude the existing runtime/legacy folders appdata/, data/, logs/ and source/. Before the first production rebuild, add the paths that are not build inputs:

appdata/
data/
logs/
source/
.forgeflow/

ForgeFlow 0.4 detects existing preserved paths and nested Git repositories that are missing from .dockerignore and reports them as a preflight warning. The tool does not silently edit a source-controlled .dockerignore; the correction should be committed to Gitea so every deployment uses the same build context.

Nested source/ repository

The server archive also contains a nested Git working tree under:

source/

Its HEAD is:

b746a52af1613f4291235f5e8165b8197a269a79

It was ahead of its own upstream and included rebase metadata in the supplied archive. The root Compose file uses build context . and does not reference source/. This strongly indicates that source/ is an abandoned or historical checkout rather than the active deployment source.

ForgeFlow reports this as a nested-repository warning and does not remove it automatically.

Recommended migration:

1. Back up /mnt/user/appdata/lumaops.
2. Verify on Unraid that docker compose config uses the root project.
3. Stop changing files in source/.
4. Rename it temporarily to source.legacy-backup.
5. Rebuild and test LumaOps from the root.
6. Remove the legacy copy only after a successful validation period.

Do not delete the root .git directory. Also do not delete the nested source/ directory as part of the first ForgeFlow test. Treat its cleanup as a separate, backed-up migration after the root deployment and rollback have both been validated.

Recommended ForgeFlow profile

Provider:       SSH / Unraid
Server folder:  lumaops
Branch:         main
Compose mode:   Repository/server Compose
Compose file:   docker-compose.yml
Clone URL:      the Git URL reachable from Unraid
Healthcheck:    the existing LumaOps health URL, when exposed
Preserve paths: .env, appdata, data, logs, config, compose.override.yml

No folder rename is required for LumaOps because lumaops already aligns with the repository name.