Use the apps' real logos as stack icons, fetched server-side (0.52.0)

0.51.0 gave every stack an icon, but a generic one: jellyfin got a clapperboard,
not the Jellyfin logo. Glyphs make a list readable; they do not make a stack
recognisable, which was the point. This resolves stacks against the selfh.st
icon catalog (~2900 self-hosted apps, the set Homarr and Homepage draw on), so
the row shows the thing people already recognise. All 83 bundled templates
resolve to their own logo.

The whole design question was *who* talks to the CDN. If the <img> points at
jsdelivr, then every client needs internet, every page load leaks the names of
somebody's stacks to a third party, and an air-gapped box gets nothing. So the
backend does it: the catalog on startup and weekly after, each logo once on
first use, both into ${DATA_DIR}/stack-icons/. Browsers keep reading icons from
the authenticated endpoint that already existed for uploads, and after the first
fetch the feature is fully offline. Logos are cached per *app*, not per stack —
verified: two stacks resolving to jellyfin produce one download.

Nothing here can fail loudly. Every entry point returns None rather than raising
when the network is absent, the catalog refresh is a task the lifespan does not
await, and an install with no outbound internet simply keeps 0.51.0's glyphs.
That fallback is also what covers a name the catalog does not know
("Mediaserver Wohnzimmer" is still a clapperboard), and the seconds after a
fresh install before the catalog lands. The glyph is derived even for stacks
that *do* have a logo, so an image that cannot be fetched degrades to something
meaningful instead of a box.

Matching gained a second source that turned out to matter more than expected:
the compose images. A stack called "medienserver" says nothing, but it pulls
lscr.io/linuxserver/jellyfin — strip the registry, the vendor and the tag and
the app is right there. Name first, then the longest run of words inside it,
then the images. It is deliberately cautious: a single word shorter than four
characters never claims a logo, because "web", "app" and "db" are all catalog
entries and a *wrong* logo is worse than a neutral glyph. A short alias table
covers what the catalog spells differently from Docker Hub (postgres →
postgresql, pihole → pi-hole, wg-easy → wireguard).

A slug arrives from the database and from query strings and then becomes a
filename, so it is pattern-checked before it is ever joined to a path, catalog
entries that are not slug-shaped are dropped on load, and a downloaded logo is
verified to start with the PNG magic bytes before being cached.

The picker searches the catalog too — pre-seeded with the stack's own name, so
opening it on "jellyfin" offers the Jellyfin logo first — which is how a wrong
match gets corrected, and how a stack can be given any app's logo on purpose.

Verified end to end against the live catalog and real downloads: list rows carry
the resolved logo, the icon endpoint serves real PNG bytes, an unmatched stack
404s (and falls through to its glyph), a hand-picked logo round-trips, reset
clears it, and a traversal slug 404s. 30 new backend tests and 12 new frontend
ones run without any network at all.

0.52.0 rather than amending 0.51.0: those images are already in the registry,
and rebuilding a published version tag with different content is exactly what
breaks the self-update checker.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/routers/stacks.py

@@ -32,6 +32,7 @@ from services import (
     auto_update_service,
     compose_service,
     icon_service,
+    logo_service,
     notify_service,
     stack_lock_service,
     stats_service,
@@ -68,6 +69,14 @@ def _get_stack_or_404(session: Session, stack_id: str) -> Stack:
     return stack
 
 
+def _auto_icon(stack: Stack) -> str | None:
+    """The logo a stack gets when nothing is configured, as an icon value."""
+    if stack.icon:
+        return None
+    slug = logo_service.auto_slug(stack.id, stack.name)
+    return f"logo:{slug}" if slug else None
+
+
 def _stack_summary(
     stack: Stack, summaries: dict | None = None, busy: dict[str, str] | None = None
 ) -> dict:
@@ -101,6 +110,9 @@ def _stack_summary(
         "name": stack.name,
         "description": stack.description,
         "icon": stack.icon,
+        # With no explicit choice, the app logo the name resolves to (the
+        # frontend falls back to a name-derived glyph when this is null).
+        "auto_icon": _auto_icon(stack),
         "status": status,
         "service_count": total,
         "running_count": running,
@@ -172,6 +184,36 @@ def stacks_updates(_user: User = Depends(get_current_user)) -> dict:
     return update_service.stacks_update_summary()
 
 
+@router.get("/icons/search")
+def search_app_logos(
+    q: str = Query("", max_length=64),
+    limit: int = Query(60, ge=1, le=200),
+    _user: User = Depends(get_current_user),
+) -> dict:
+    """Search the app-logo catalog (Jellyfin, Postgres, Gitea, …).
+
+    ``ready`` is false when the catalog has not been downloaded yet — a box with
+    no outbound internet, or the very first minute after a fresh install. The
+    picker says so instead of looking empty and broken.
+    """
+    return {
+        "ready": logo_service.load_catalog() is not None,
+        "icons": logo_service.search(q, limit),
+    }
+
+
+@router.get("/icons/logo/{slug}")
+async def get_app_logo(
+    slug: str,
+    _user: User = Depends(get_current_user),
+) -> FileResponse:
+    """One catalog logo by slug, for the picker's result grid."""
+    path = await logo_service.ensure_logo(slug)
+    if not path:
+        raise HTTPException(status_code=404, detail=f"No logo for '{slug}'")
+    return _icon_response(path, "image/png", f"{slug}.png")
+
+
 @router.get("/{stack_id}")
 def get_stack(
     stack_id: str,
@@ -194,6 +236,7 @@ def get_stack(
         "name": stack.name,
         "description": stack.description,
         "icon": stack.icon,
+        "auto_icon": _auto_icon(stack),
         "status": status,
         "yaml": compose_service.read_compose(stack_id),
         # The .env is where credentials live by convention, so it is withheld
@@ -260,6 +303,7 @@ async def delete_stack(
     if delete_files:
         compose_service.delete_stack_files(stack_id)
     icon_service.remove(stack_id)
+    logo_service.forget(stack_id)
     session.delete(stack)
     session.commit()
     audit_service.record(
@@ -306,28 +350,37 @@ def clone_stack(
 
 
 @router.get("/{stack_id}/icon")
-def get_stack_icon(
+async def get_stack_icon(
     stack_id: str,
     session: Session = Depends(get_session),
     _user: User = Depends(get_current_user),
 ) -> FileResponse:
-    """Serve a stack's uploaded icon.
+    """Serve a stack's image icon — an upload, or the app logo it resolved to.
 
     Authenticated like everything else, which is why the frontend fetches it
     through the API client and renders the blob rather than pointing an
     ``<img src>`` straight at this URL (that request would carry no token).
+    It is also what keeps the browser off the icon CDN: an app logo is
+    downloaded once by this process and served from disk from then on.
     """
     stack = _get_stack_or_404(session, stack_id)
-    path = icon_service.file_for(stack_id, stack.icon)
-    if not path:
-        raise HTTPException(status_code=404, detail="This stack has no custom icon")
-    ext = icon_service.custom_ext(stack.icon) or ""
+    if (path := icon_service.file_for(stack_id, stack.icon)):
+        ext = icon_service.custom_ext(stack.icon) or ""
+        return _icon_response(path, icon_service.content_type(ext), f"{stack_id}.{ext}")
+
+    slug = icon_service.logo_slug(stack.icon) or icon_service.logo_slug(_auto_icon(stack))
+    if slug and (path := await logo_service.ensure_logo(slug)):
+        return _icon_response(path, "image/png", f"{slug}.png")
+    raise HTTPException(status_code=404, detail="This stack has no image icon")
+
+
+def _icon_response(path: str, media_type: str, filename: str) -> FileResponse:
     return FileResponse(
         path,
-        media_type=icon_service.content_type(ext),
+        media_type=media_type,
         # An SVG opened as a top-level document would run its own script in the
         # API's origin. Nothing here is ever meant to be a document.
-        headers={"Content-Disposition": f'attachment; filename="{stack_id}.{ext}"'},
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
     )