Skip to content

Add ZimaOS install guide, fix stale upstream pin (#124) - #125

Merged
gantoine merged 4 commits into
mainfrom
docs/zimaos-and-env-var-sync
Aug 31, 2026
Merged

Add ZimaOS install guide, fix stale upstream pin (#124)#125
gantoine merged 4 commits into
mainfrom
docs/zimaos-and-env-var-sync

Conversation

@gantoine

Copy link
Copy Markdown
Member

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 inside roms/. 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.template at the ref pinned in scripts/sources.toml, and that pin was stale: 5.1.0-beta.2 (2026-07-26) while latest is 5.2.0 (2026-08-20). ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES 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

administration/scheduled-tasks.md listed Cleanup Orphaned Resources as a Manual task with no env var, directly contradicting the fix above. That table comes from a hardcoded list in gen_scheduled_tasks.py marked "as of 4.8.x". Checking it against backend/tasks/ at 5.2.0 showed every scheduled row's env var name was invented — none of these exist upstream:

In the docs Reality
SWITCH_TITLEDB_FETCH_INTERVAL_CRON SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON
LAUNCHBOX_SYNC_INTERVAL_CRON SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON
IMAGE_CONVERSION_INTERVAL_CRON SCHEDULED_CONVERT_IMAGES_TO_WEBP_CRON
RETROACHIEVEMENTS_SYNC_INTERVAL_CRON SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON
NETPLAY_CLEANUP_INTERVAL_CRON no env var, hardcoded always-on
WATCHER_ENABLED ENABLE_RESCAN_ON_FILESYSTEM_CHANGE

7f6f558 ("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.toml claims the pin is "bumped automatically by .github/workflows/romm-release-bump.yml", but that workflow does not exist, and gen_scheduled_tasks.py still 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 --strict reports 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.yml files, both confirmed against a clean stash of main.

🤖 Generated with Claude Code

gantoine and others added 3 commits August 31, 2026 07:55
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>
@gantoine
gantoine merged commit 3b2fe83 into main Aug 31, 2026
4 checks passed
@gantoine
gantoine deleted the docs/zimaos-and-env-var-sync branch August 31, 2026 12:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES Missing from Docs

1 participant