Add ZimaOS install guide, fix stale upstream pin (#124) - #125
Merged
Conversation
RomM ships in the ZimaOS App Store, so the install is a single click with no compose file or database setup needed. Adapted from a walkthrough contributed by the ZimaSpace team, reshaped to match the structure of the other install guides. Adds the prerequisites the source material omitted: generating ROMM_AUTH_SECRET_KEY, setting up metadata providers before the first scan, and the folder-naming requirement inside roms/. Screenshots extracted from the contributed PDF. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Fixes #124. ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES was missing from the env var reference because scripts/sources.toml still pinned 5.1.0-beta.2 (2026-07-26) while latest is 5.2.0 (2026-08-20). The variable landed upstream after the pinned ref, so the generator never saw it. Bumped the pin and regenerated. The bump also picks up genuine upstream drift, each verified against env.template: new REDIS_SAVE_POLICY, reworded KIOSK_MODE, SCAN_WORKERS 2 -> 1, WEB_SERVER_CONCURRENCY 3 -> 1, one new platform (Doom) and four metadata-provider icon changes. The same variable was wrong a second time: the scheduled-tasks table listed Cleanup Orphaned Resources as a Manual task with no env var. That table came from a hardcoded list in gen_scheduled_tasks.py marked "as of 4.8.x", and checking it against backend/tasks/ at 5.2.0 showed every scheduled row's env var name was invented. None of SWITCH_TITLEDB_FETCH_INTERVAL_CRON, LAUNCHBOX_SYNC_INTERVAL_CRON, IMAGE_CONVERSION_INTERVAL_CRON, RETROACHIEVEMENTS_SYNC_INTERVAL_CRON, NETPLAY_CLEANUP_INTERVAL_CRON or WATCHER_ENABLED exist upstream. Commit 7f6f558 was the same class of bug found one variable at a time. Rewrote the registry from each task's constructor, added an Enable var column alongside the cron var, and added the four tasks missing entirely (upload tmp cleanup, ZIP cache cleanup, recompute save hashes, sync folder watcher). Also corrected the prose claim that every task has an ENABLE_* var, since three housekeeping tasks are hardcoded always-on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
trunk check runs oxipng and flags unoptimized images, so the PNGs as extracted from the PDF would have failed this PR's own trunk-check. 784K -> 692K, lossless. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The section is two sentences and two screenshots, so numbered step headings were scaffolding around prose that already reads in order. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two unrelated changes, one commit each.
1. ZimaOS install guide
RomM ships in the ZimaOS App Store, so the install is a single click with no compose file or database setup. Adapted from a walkthrough contributed by the ZimaSpace team, reshaped to match the structure of the other install guides.
Added the prerequisites the source material omitted: generating
ROMM_AUTH_SECRET_KEY, setting up metadata providers before the first scan, and the folder-naming requirement insideroms/. Screenshots extracted from the contributed PDF.2. Fixes #124
The root cause isn't a missing hand-written entry. The env var table is generated from upstream
env.templateat the ref pinned inscripts/sources.toml, and that pin was stale:5.1.0-beta.2(2026-07-26) while latest is5.2.0(2026-08-20).ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCESlanded upstream after the pinned ref, so the generator never saw it.Bumped the pin and regenerated. The bump also picks up genuine upstream drift, each verified against
env.template:REDIS_SAVE_POLICYKIOSK_MODESCAN_WORKERS2 → 1WEB_SERVER_CONCURRENCY3 → 1The same variable was wrong a second time
administration/scheduled-tasks.mdlisted Cleanup Orphaned Resources as a Manual task with no env var, directly contradicting the fix above. That table comes from a hardcoded list ingen_scheduled_tasks.pymarked "as of 4.8.x". Checking it againstbackend/tasks/at 5.2.0 showed every scheduled row's env var name was invented — none of these exist upstream:SWITCH_TITLEDB_FETCH_INTERVAL_CRONSCHEDULED_UPDATE_SWITCH_TITLEDB_CRONLAUNCHBOX_SYNC_INTERVAL_CRONSCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRONIMAGE_CONVERSION_INTERVAL_CRONSCHEDULED_CONVERT_IMAGES_TO_WEBP_CRONRETROACHIEVEMENTS_SYNC_INTERVAL_CRONSCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRONNETPLAY_CLEANUP_INTERVAL_CRONWATCHER_ENABLEDENABLE_RESCAN_ON_FILESYSTEM_CHANGE7f6f558 ("Fix SCAN_INTERVAL_CRON env var doesn't exist") was the same class of bug, found one variable at a time.
Rewrote the registry from each task's constructor, added an Enable var column alongside the cron var, and added the four tasks missing entirely (upload tmp cleanup, ZIP cache cleanup, recompute save hashes, sync folder watcher). Also corrected the prose claim that every task has an
ENABLE_*var, since three housekeeping tasks are hardcoded always-on.Follow-up
This will go stale again.
sources.tomlclaims the pin is "bumped automatically by.github/workflows/romm-release-bump.yml", but that workflow does not exist, andgen_scheduled_tasks.pystill hardcodes its list instead of fetching upstream. Both are addressed in a stacked PR rather than here, to keep this one reviewable.Testing
mkdocs build --strictreports no broken links. Generators are idempotent (re-running reproduces the same output). Remaining warnings are pre-existing and unrelated: no libcairo installed locally, and prettier on three*.docker-compose.ymlfiles, both confirmed against a clean stash ofmain.🤖 Generated with Claude Code