romledger 0.2.0__tar.gz

romledger-0.2.0/.dockerignore

@@ -0,0 +1,6 @@
+*
+!pyproject.toml
+!uv.lock
+!README.md
+!src
+src/**/__pycache__

romledger-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+dist/
+build/
+*.egg-info/

romledger-0.2.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,7 @@
+{
+  "config": {
+    "MD013": false,
+    "MD033": { "allowed_elements": ["picture", "source", "img"] }
+  },
+  "ignores": ["node_modules", ".venv"]
+}

romledger-0.2.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.2.0
+
+- Install from PyPI: `uv tool install romledger` or `pipx install romledger`.
+- The container image is published to `ghcr.io/kjiwa/romledger` for `linux/amd64` and
+  `linux/arm64`, and the Compose example pulls it.
+- Each release attaches `romledger-extension-<version>.zip` for loading the extension unpacked.
+- The extension options page starts with `http://127.0.0.1:8730`.
+- Documentation and examples no longer assume a particular host, a network share or RomM; the
+  contributor material moved to `CONTRIBUTING.md`.
+
+## 0.1.0
+
+First release.
+
+- `dats`, `scan`, `status` and `missing` compare a ROM library against No-Intro and Redump DATs
+  through igir and report what each platform has and lacks.
+- `import` files downloads from an inbox into the `roms/<platform>/` library layout, which RomM also reads.
+- `fetch` downloads missing games from CoolROM and the Internet Archive.
+- `serve` runs a local dashboard and JSON API with a DAT hash index and a lookup endpoint.
+- `canary` checks that the supported sites and the igir pin still match; CI runs it weekly.
+- A Dockerfile and Compose example, with deployment docs.
+- A browser extension that marks games you have, are missing or have waiting in the inbox on Vimm's
+  Lair, CoolROM and the Internet Archive.
+- A guide to playing the library on common devices and emulators.

romledger-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing
+
+## Set up and check
+
+You need [uv](https://docs.astral.sh/uv/) and Node.js 22.22+.
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest -q
+npx --yes markdownlint-cli2@0.23.3 "**/*.md"
+```
+
+Tests marked `igir` run the real igir and are skipped by default; run them with
+`uv run pytest -m igir --no-cov`.
+
+Browser-driven checks run Chromium against fictional data:
+
+```sh
+sh scripts/browser-check.sh
+sh scripts/extension-check.sh
+sh scripts/image-check.sh
+sh scripts/screenshots.sh
+```
+
+`screenshots.sh` regenerates `docs/images/*.png`.
+
+## Extension
+
+```sh
+node --test "tests/extension/*.test.js"
+npx --yes addons-linter@10.14.0 extension
+sh scripts/extension-check.sh
+```
+
+`extension-check.sh` loads the unpacked extension in Chromium against a fictional library and
+fixture pages. `addons-linter` warns that Firefox ignores `background.service_worker`; that key is
+for Chrome, and Firefox uses `background.scripts`. The page parsers are in `extension/content/` and
+`extension/lib/romledger.js`.
+
+## Drift checks
+
+`romledger canary` makes about 50 requests to detect site changes before a download fails. It needs
+no config file and follows the same robots.txt and spacing rules as `fetch`. The weekly
+`canary` workflow runs it; run it by hand with `romledger canary` or `romledger canary --json`.
+
+It checks that:
+
+- CoolROM's `/roms/` lists every `coolrom` code in the registry, one section page parses, and one
+  `dlpop.php` page still holds a signed link. The link itself is never requested.
+- Vimm's Lair `/vault/` lists every `vimm` code in the registry, and one list page has game rows.
+  Game pages are never requested.
+- The Internet Archive's metadata for `No-Intro_NES` lists files with checksums.
+- Every DAT named in `src/romledger/platforms.toml` exists in libretro-database.
+- The latest igir release matches `IGIR_VERSION`.
+
+A finding means a site, the registry, or a pin needs a change. Each has a stable key such as
+`vimm:new-platform:Amiga`, `vimm:missing-platform:PS3`, `coolrom:contract:section`,
+`dat:missing:nes`, or `igir:update:v5.8.0`. `contract` keys mean a page changed shape; a platform
+index page with no platform links at all is `<site>:contract:platform-links`, while a registry code
+absent from an otherwise normal index is `<site>:missing-platform:<code>`. `dat:missing` means HTTP
+404. The command exits 1 when there are findings.
+
+A note means a check could not conclude: a network error, HTTP 403, 429, or 5xx, any other
+unexpected status, a bot challenge page, a robots.txt refusal, or (for GitHub's API) a redirect.
+Notes are not findings and leave the exit status at 0. The rest of that site's checks are skipped
+and listed as unverified: `--json` prints `{"findings": [...], "inconclusive": [...]}`, where
+`inconclusive` holds the key prefixes (`coolrom`, `vimm`, `internet-archive`, `dat`, `igir`, and
+the skipped checks' keys) that were not verified; without `--json` they print as
+`unverified <prefix>`. The CoolROM download check is also unverified when the section page gave no
+row to use. The next run tries again.
+
+The workflow runs `scripts/canary-issues.sh` on the JSON. It opens one issue titled
+`canary: <key>` per finding, leaves an open one alone, and closes an open one with a comment once
+its finding is gone, unless its key starts with an unverified prefix. A finding whose issue was
+closed as completed opens a new issue; close the issue as "not planned" to silence it.
+
+To support a platform a site lists, add its code to that platform's row in
+`src/romledger/platforms.toml`, or add a new row with `dat`, `vimm`, and `coolrom` keys. To decline
+it, add the code to the `[ignore]` table in the same file.
+
+Fix by key:
+
+- `<site>:new-platform:<code>`: the site lists a platform the registry does not know. Add
+  `<site> = "<code>"` to that platform in `src/romledger/platforms.toml`, or add the code to
+  `[ignore]` there.
+- `<site>:missing-platform:<code>`: the site's platform list no longer has a registry code. Correct
+  the code in `platforms.toml`.
+- `<site>:contract:platform-links`: the site's platform index page has no platform links. Update
+  romledger or report it.
+- `coolrom:contract:section`, `coolrom:contract:download-link`, `vimm:contract:list`,
+  `internet-archive:contract:metadata`: a page no longer has what romledger expects, so `fetch` for
+  that source will fail the same way. Update romledger or report it.
+- `dat:missing:<slug>`: libretro-database has no such DAT. Correct `dat` for that platform in
+  `platforms.toml`.
+- `igir:update:<tag>`: a newer igir exists. Run `uv run pytest -m igir --no-cov`, then update
+  `IGIR_VERSION` in `src/romledger/igir.py`.
+- `igir:contract:release`: GitHub's release answer has no tag name. Report it.
+
+## Release
+
+Releases use [gh-cut](https://github.com/kjiwa/gh-cut): `gh cut <version>` bumps the version in
+`pyproject.toml`, `extension/manifest.json` and `uv.lock` through `scripts/release-hooks.sh`, merges
+the bump, tags it and creates the GitHub release. Add the version's section to `CHANGELOG.md`
+first. Publishing the release runs `.github/workflows/publish.yml`.

romledger-0.2.0/Dockerfile

@@ -0,0 +1,33 @@
+FROM node:26-trixie-slim@sha256:193fe51b64e77981119c98c2002c9e32a70e2f006fb4d25068ce0558998917f0 AS igir
+COPY src/romledger/igir.py /tmp/igir.py
+RUN version=$(sed -n 's/^IGIR_VERSION = "\(.*\)"$/\1/p' /tmp/igir.py) \
+    && test -n "$version" \
+    && npm install --global --prefix /opt/igir "igir@${version}"
+
+FROM python:3.14-slim-trixie@sha256:a2b82f3c48559aa0a8446d9af49826b6e2b2016f4cd2afabfe6013ec53729170
+COPY --from=ghcr.io/astral-sh/uv:0.13.0@sha256:cdc6093146eb3ff6a40107b38f008b789e050e77ad87865e381d9917da55a168 /uv /usr/local/bin/uv
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libatomic1 \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=igir /usr/local/bin/node /usr/local/bin/node
+COPY --from=igir /opt/igir /opt/igir
+
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
+WORKDIR /app
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --locked --no-dev --no-install-project
+COPY src ./src
+RUN uv sync --locked --no-dev
+
+RUN useradd --uid 1000 --create-home romledger \
+    && mkdir /config /data \
+    && chown romledger /data
+
+ENV PATH="/app/.venv/bin:/opt/igir/bin:${PATH}" \
+    ROMLEDGER_CONFIG=/config/config.toml \
+    ROMLEDGER_DATA=/data/romledger
+USER romledger
+LABEL org.opencontainers.image.source="https://github.com/kjiwa/romledger"
+EXPOSE 8730
+ENTRYPOINT ["romledger"]
+CMD ["serve", "--host", "0.0.0.0"]

romledger-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamil Jiwa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

romledger-0.2.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: romledger
+Version: 0.2.0
+Summary: Track which retro games you have and which are missing, verified against No-Intro and Redump DATs.
+Project-URL: Homepage, https://github.com/kjiwa/romledger
+Project-URL: Documentation, https://github.com/kjiwa/romledger/tree/master/docs
+Project-URL: Issues, https://github.com/kjiwa/romledger/issues
+Project-URL: Changelog, https://github.com/kjiwa/romledger/blob/master/CHANGELOG.md
+Author: Kamil Jiwa
+License-Expression: MIT
+License-File: LICENSE
+Keywords: emulation,igir,no-intro,redump,retro-gaming,romm,roms
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.143.0
+Requires-Dist: httpx[socks]>=0.28.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: uvicorn>=0.54.0
+Description-Content-Type: text/markdown
+
+# romledger
+
+Track which retro games you have and which are missing, verified against No-Intro and Redump DATs.
+It runs on one computer: point it at a folder of ROMs and it reports, per platform, what is there
+and what is not.
+
+## Status
+
+Works today:
+
+- Validate a config file (`romledger config`)
+- Download No-Intro and Redump DATs (`romledger dats update`)
+- Match your library and inboxes to the DATs (`romledger scan`)
+- Show progress per platform (`romledger status`)
+- List missing games, with Vimm's Lair search links (`romledger missing nes --links`)
+- Import from the inboxes into a per-platform folder layout (`romledger import`)
+- Browse progress, missing games and the inbox, and upload files, in a local dashboard (`romledger serve`)
+- Download missing games from CoolROM and the Internet Archive (`romledger fetch`)
+- Mark games as in your library or missing while you browse Vimm's Lair, CoolROM and the Internet
+  Archive (browser extension)
+- Check that the supported sites and the igir pin still match (`romledger canary`; runs weekly in CI)
+
+Vimm's Lair is manual; see [docs/sources.md](https://github.com/kjiwa/romledger/blob/master/docs/sources.md).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/overview-desktop-dark.png">
+  <img alt="The romledger overview page: one card per platform with a progress bar and counts of games had, in the inbox, missing and unmatched." src="https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/overview-desktop-light.png">
+</picture>
+
+![A terminal running romledger status, which lists wanted, have, inbox, missing and unmatched counts per platform, then romledger missing snes, which lists missing games.](https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/demo.gif)
+
+## How it fits
+
+- [igir](https://igir.io) matches files to DATs and moves them into place.
+- romledger decides what you have and what is missing.
+- [RomM](https://romm.app) is optional. The library layout is RomM's folder naming
+  (`roms/<platform>/`), and romledger works the same without RomM.
+
+## Install
+
+Requires Python 3.11+ and Node.js 22.22+ (romledger runs [igir](https://igir.io) through `npx`).
+
+```sh
+uv tool install romledger
+```
+
+or, with [pipx](https://pipx.pypa.io):
+
+```sh
+pipx install romledger
+```
+
+## Configure
+
+Create `~/.config/romledger/config.toml`:
+
+```toml
+[library]
+roms = "~/roms/library"
+inboxes = ["~/roms/inbox"]
+
+[platforms.nes]
+```
+
+Both directories must exist. Platform names are the folder names RomM uses, such as `nes` and
+`snes`. An unknown name makes `romledger config` print the known ones. `dat` is filled in for
+known platforms.
+
+Check it, then fetch DATs and scan:
+
+```sh
+romledger config
+romledger dats update
+romledger scan
+romledger status
+romledger serve --open
+```
+
+See [docs/setup.md](https://github.com/kjiwa/romledger/blob/master/docs/setup.md) for all options,
+[docs/deploy.md](https://github.com/kjiwa/romledger/blob/master/docs/deploy.md) to run it as a container,
+[docs/extension.md](https://github.com/kjiwa/romledger/blob/master/docs/extension.md) for the browser extension,
+[docs/playing.md](https://github.com/kjiwa/romledger/blob/master/docs/playing.md) to play what you collect,
+[docs/sources.md](https://github.com/kjiwa/romledger/blob/master/docs/sources.md) for download sources and
+[docs/troubleshooting.md](https://github.com/kjiwa/romledger/blob/master/docs/troubleshooting.md) for error messages.
+
+To work on romledger, see [CONTRIBUTING.md](https://github.com/kjiwa/romledger/blob/master/CONTRIBUTING.md).

romledger-0.2.0/README.md

@@ -0,0 +1,86 @@
+# romledger
+
+Track which retro games you have and which are missing, verified against No-Intro and Redump DATs.
+It runs on one computer: point it at a folder of ROMs and it reports, per platform, what is there
+and what is not.
+
+## Status
+
+Works today:
+
+- Validate a config file (`romledger config`)
+- Download No-Intro and Redump DATs (`romledger dats update`)
+- Match your library and inboxes to the DATs (`romledger scan`)
+- Show progress per platform (`romledger status`)
+- List missing games, with Vimm's Lair search links (`romledger missing nes --links`)
+- Import from the inboxes into a per-platform folder layout (`romledger import`)
+- Browse progress, missing games and the inbox, and upload files, in a local dashboard (`romledger serve`)
+- Download missing games from CoolROM and the Internet Archive (`romledger fetch`)
+- Mark games as in your library or missing while you browse Vimm's Lair, CoolROM and the Internet
+  Archive (browser extension)
+- Check that the supported sites and the igir pin still match (`romledger canary`; runs weekly in CI)
+
+Vimm's Lair is manual; see [docs/sources.md](https://github.com/kjiwa/romledger/blob/master/docs/sources.md).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/overview-desktop-dark.png">
+  <img alt="The romledger overview page: one card per platform with a progress bar and counts of games had, in the inbox, missing and unmatched." src="https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/overview-desktop-light.png">
+</picture>
+
+![A terminal running romledger status, which lists wanted, have, inbox, missing and unmatched counts per platform, then romledger missing snes, which lists missing games.](https://raw.githubusercontent.com/kjiwa/romledger/master/docs/images/demo.gif)
+
+## How it fits
+
+- [igir](https://igir.io) matches files to DATs and moves them into place.
+- romledger decides what you have and what is missing.
+- [RomM](https://romm.app) is optional. The library layout is RomM's folder naming
+  (`roms/<platform>/`), and romledger works the same without RomM.
+
+## Install
+
+Requires Python 3.11+ and Node.js 22.22+ (romledger runs [igir](https://igir.io) through `npx`).
+
+```sh
+uv tool install romledger
+```
+
+or, with [pipx](https://pipx.pypa.io):
+
+```sh
+pipx install romledger
+```
+
+## Configure
+
+Create `~/.config/romledger/config.toml`:
+
+```toml
+[library]
+roms = "~/roms/library"
+inboxes = ["~/roms/inbox"]
+
+[platforms.nes]
+```
+
+Both directories must exist. Platform names are the folder names RomM uses, such as `nes` and
+`snes`. An unknown name makes `romledger config` print the known ones. `dat` is filled in for
+known platforms.
+
+Check it, then fetch DATs and scan:
+
+```sh
+romledger config
+romledger dats update
+romledger scan
+romledger status
+romledger serve --open
+```
+
+See [docs/setup.md](https://github.com/kjiwa/romledger/blob/master/docs/setup.md) for all options,
+[docs/deploy.md](https://github.com/kjiwa/romledger/blob/master/docs/deploy.md) to run it as a container,
+[docs/extension.md](https://github.com/kjiwa/romledger/blob/master/docs/extension.md) for the browser extension,
+[docs/playing.md](https://github.com/kjiwa/romledger/blob/master/docs/playing.md) to play what you collect,
+[docs/sources.md](https://github.com/kjiwa/romledger/blob/master/docs/sources.md) for download sources and
+[docs/troubleshooting.md](https://github.com/kjiwa/romledger/blob/master/docs/troubleshooting.md) for error messages.
+
+To work on romledger, see [CONTRIBUTING.md](https://github.com/kjiwa/romledger/blob/master/CONTRIBUTING.md).

romledger-0.2.0/compose.yaml

@@ -0,0 +1,13 @@
+services:
+  romledger:
+    build: .
+    image: ghcr.io/kjiwa/romledger:latest
+    init: true
+    restart: unless-stopped
+    mem_limit: 2g
+    ports:
+      - "${ROMLEDGER_BIND:-127.0.0.1}:8730:8730"
+    volumes:
+      - ./config:/config:ro
+      - ./data:/data
+      - ${ROMLEDGER_LIBRARY:-./library}:/library

romledger-0.2.0/docs/demo.tape

@@ -0,0 +1,15 @@
+Output docs/images/demo.gif
+Set Shell "bash"
+Set FontSize 16
+Set Width 1000
+Set Height 520
+Set Padding 20
+Set TypingSpeed 60ms
+Hide
+Type "PS1='$ '" Enter
+Type "clear" Enter
+Show
+Type "romledger status" Enter
+Sleep 3s
+Type "romledger missing snes | head -n 8" Enter
+Sleep 4s

romledger-0.2.0/docs/deploy.md

@@ -0,0 +1,183 @@
+# Deploy
+
+Run romledger as a container on a home server, a single-board computer or a workstation, next to
+your library. The image bundles Python, Node.js and igir for `linux/amd64` and `linux/arm64`.
+It is published to the GitHub Container Registry; you can also build it yourself.
+
+## Requirements
+
+- Docker with Compose on the machine that runs it. Buildx is needed only to build the image yourself.
+- A library directory laid out as in [setup.md](setup.md): `roms/<platform>/` and an `inbox/`.
+- About 2 GiB of memory for the container. A scan of the NES, PS1, PS2 and GBA DATs peaked near
+  1 GiB.
+
+## Get the image
+
+Pull it on the machine that will run it:
+
+```sh
+docker pull ghcr.io/kjiwa/romledger:latest
+```
+
+Releases are also tagged by version, such as `ghcr.io/kjiwa/romledger:0.2.0`. To build it
+yourself instead, run this from a checkout of the repository:
+
+```sh
+docker build -t ghcr.io/kjiwa/romledger:latest .
+```
+
+`docker compose up -d --build` (see [Run it](#run-it)) builds it too. To build for another
+architecture, name the target platform. Buildx emulates it when it differs from the host, which
+is slower than a native build:
+
+```sh
+docker buildx build --platform linux/arm64 -t ghcr.io/kjiwa/romledger:latest -o type=docker,dest=romledger.tar .
+```
+
+- Docker Desktop (macOS, Windows) emulates other architectures out of the box.
+- On Linux with Docker Engine, register the emulators once:
+  `docker run --privileged --rm tonistiigi/binfmt --install all`.
+- Use `linux/arm64` for a Raspberry Pi 4 or 5 and other 64-bit ARM boards, `linux/amd64` for
+  most PCs and servers.
+
+## Move the image to another host
+
+If you built elsewhere, copy the archive and load it. A pipe over SSH needs no intermediate file:
+
+```sh
+docker save ghcr.io/kjiwa/romledger:latest | ssh HOST docker load
+```
+
+Or from a file you built with `-o type=docker,dest=romledger.tar`:
+
+```sh
+scp romledger.tar HOST:
+ssh HOST docker load -i romledger.tar
+```
+
+`docker load` prints `Loaded image: ghcr.io/kjiwa/romledger:latest`.
+
+## Run it
+
+Work in a checkout, where [compose.yaml](https://github.com/kjiwa/romledger/blob/master/compose.yaml)
+lives, or copy that file to the host. Create the config:
+
+```sh
+mkdir config data
+sudo chown 1000 data
+```
+
+Write `config/config.toml` with container paths, as in [setup.md](setup.md):
+
+```toml
+[library]
+roms = "/library/roms"
+inboxes = ["/library/inbox"]
+
+[platforms.nes]
+```
+
+Point `ROMLEDGER_LIBRARY` at your library directory (default `./library`) and start it:
+
+```sh
+ROMLEDGER_LIBRARY=/mnt/roms docker compose up -d --build
+```
+
+`--build` builds the image from the checkout. Without a checkout, load an image as in
+[Move the image to another host](#move-the-image-to-another-host) and leave `--build` off.
+
+The port is published on `127.0.0.1` only. To reach the dashboard from other machines on your
+network, also set `ROMLEDGER_BIND` to the host's address, or `0.0.0.0` for every interface.
+
+The container runs as user 1000. That user must be able to write `data/` (hence the `chown`), the
+`roms/` tree and the inbox. `data/romledger/` holds the DATs, igir's hash cache and `state.db`; keep it on a local disk, not
+on the network share.
+
+Read the sign-in link from the log and open it once in a browser. The link names `localhost`; when
+you open it from another machine, replace `localhost` with the address you reach the host at:
+
+```sh
+docker compose logs romledger
+```
+
+The dashboard is plain HTTP; see [Access token](setup.md#access-token) before exposing the port
+beyond a network you trust.
+
+Fetch DATs and scan, as on the command line:
+
+```sh
+docker compose exec romledger romledger dats update
+docker compose exec romledger romledger scan
+```
+
+To run a command on a schedule, call it from cron or a systemd timer with `-T`, which disables
+the terminal:
+
+```sh
+docker compose -f /path/to/compose.yaml exec -T romledger romledger scan
+```
+
+## Use it beside RomM
+
+RomM reads the same `roms/<platform>/` folders that `import` fills. Mount the library directory
+into RomM's container as its library, following [RomM's documentation](https://docs.romm.app),
+and let RomM's scheduled rescan pick up new games; see `hooks.after_import` in
+[setup.md](setup.md).
+
+## Update
+
+Pull the new image and recreate the container:
+
+```sh
+docker compose pull
+docker compose up -d
+```
+
+From a source checkout, pull the new source and run `docker compose up -d --build` instead.
+If you load images instead, load the new one and run `docker compose up -d`.
+
+Compose recreates the container when the `ghcr.io/kjiwa/romledger:latest` image has changed. `data/` survives.
+
+## Mount a network share
+
+Mount the share on the host, then bind-mount it into the container. The container sees only the
+path you pass in `ROMLEDGER_LIBRARY`.
+
+### Linux, NFS
+
+Add a line to `/etc/fstab` that mounts on first access (`x-systemd.automount`), so a share that is
+down at boot does not block it:
+
+```text
+server:/export/roms  /mnt/roms  nfs  _netdev,x-systemd.automount,x-systemd.idle-timeout=60  0  0
+```
+
+Then run `sudo systemctl daemon-reload && sudo systemctl start mnt-roms.automount` (the unit
+name is the mount path with `/` replaced by `-`). Check with `ls /mnt/roms`.
+
+### Linux, SMB
+
+Put the login in a file only root can read, `/etc/romledger-smb`:
+
+```text
+username=USER
+password=PASSWORD
+```
+
+```sh
+sudo chmod 600 /etc/romledger-smb
+```
+
+Then add to `/etc/fstab`, with the uid and gid of the user the container runs as (1000):
+
+```text
+//server/roms  /mnt/roms  cifs  credentials=/etc/romledger-smb,uid=1000,gid=1000,_netdev,x-systemd.automount  0  0
+```
+
+`uid` and `gid` set the owner of every file when the server does not report one. If the server
+needs a specific protocol version, add `vers=3.0` (or another value from `man mount.cifs`).
+
+### macOS
+
+Mount the share in Finder (Go, Connect to Server, `smb://server/roms`) or with `mount_smbfs`.
+It appears under `/Volumes/roms`; pass that path as `ROMLEDGER_LIBRARY`.