ADR 0030: GeoNames Import Source Modes
Status: accepted Date: 2026-05-22
Context
ADR 0029 accepts managed GeoNames install/import controls. The remaining transport question is how Memories obtains GeoNames files for import. Self-hosted installations vary: some have normal outbound internet access, some are intentionally locked down, and some operators prefer downloading files themselves for audit, caching, or reproducibility.
Memories should make the common case easy without making network download mandatory.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A. Direct managed download only | Memories downloads GeoNames files from configured URLs | Best UX | Fails for offline/locked-down installs; app network access required |
| B. Admin-uploaded files only | Super Admin uploads GeoNames files through UI/API | Works offline; explicit file provenance | Awkward for large files; browser upload limits/timeouts |
| C. Configured local directory only | Operator places files in a mounted import directory | Good for large/offline files; scriptable | More filesystem/deploy setup; less friendly UI |
| D. Hybrid source modes | Support direct download, admin upload for small/specific files, and configured local directory | Flexible for self-hosters | More implementation and validation paths |
Decision
Support hybrid GeoNames import source modes:
- Direct managed download: Super Admin selects countries/regions/levels/languages; Core downloads required GeoNames files from configured/default source URLs after explicit confirmation.
- Configured local import directory: operator places GeoNames files in a mounted directory; Super Admin selects files/scope from Admin UI/API; preferred fallback for large/offline/locked-down imports.
- Admin-uploaded files: optional convenience path for small extracts or metadata files, subject to file-size limits and resumability constraints.
All modes must produce the same GazetteerImportProfile and provenance shape: source mode, source URL or file identity/path, checksums where available, selected countries/regions, selected levels, selected languages, dataset dump date/version, attribution/license, imported/skipped counts, and errors.
Direct download is the convenience default in connected deployments, but it must not run automatically on fresh installs. Local directory import is the required offline/locked-down path. Admin upload may be implemented later if large-file UX is not worth first-slice complexity.
Consequences
Positive
- Supports both convenient home installs and locked-down/offline self-hosting.
- Avoids making browser upload the only path for large GeoNames files.
- Keeps import provenance uniform across source modes.
- Allows future scripted/operator-managed dataset caching.
Negative / Costs
- More Admin/API/job states than one transport path.
- Local directory mode needs documented Docker Compose volume/path configuration.
- Direct download needs timeout, resume/retry, checksum/source validation where possible, and clear errors.
- Admin upload may be deferred if it adds too much complexity.
Revisit Triggers
Revisit this decision if:
- Direct GeoNames download terms discourage app-managed download.
- Most operators prefer volume/file import and direct download is rarely used.
- Admin-uploaded files prove unnecessary or too fragile for large datasets.
- A future package manager or dataset mirror makes a single source mode sufficient.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference