Give every stack an icon, and put the status on it (0.51.0)

Stacks were a name and a coloured dot. The dot carried the status but nothing
carried identity, so a list of twenty stacks read as twenty identical rows.
This gives each one an icon in front of its name and moves the status onto that
icon as a halo in the status colour, which is the thing the eye lands on anyway.

The constraint that shaped the design: people already have stacks. Asking them
to pick an icon for each one before the feature does anything would mean it
never gets used, so the icon is *derived* from the stack's name and the column
stays empty until somebody overrides it. ~700 keywords in 79 groups cover the
self-hosted long tail (jellyfin -> clapperboard, vaultwarden -> key,
home-assistant -> house) plus generic English and German terms; the longest
match wins, so photoprism beats a bare photo, and short keywords like "tv" only
match as whole words. No backfill, no migration, and a rename moves the icon
with it.

That is also why the catalog and the matcher live in the frontend. It is the
only place that can render an icon, so a copy in the backend would be a list to
keep in sync and nothing else. The server validates the shape of the stored
value and stores uploads; it never needs to know what "lucide:database" looks
like. An icon name that later leaves the catalog falls back to the derived one
rather than blanking the row.

Overriding happens in two places, because there are two moments: the editor
(holding a chosen file until the stack exists, since uploading needs an id) and
a click on the icon on the detail page, which is how a stack that has existed
for a year gets one without a trip through the editor.

Uploads are classified by their bytes, not by the filename or Content-Type the
browser claims, and land in ${DATA_DIR}/stack-icons/ under the stack id. SVG is
allowed — <img> does not execute it — but the endpoint serves every icon as an
attachment so one can never be opened as a document in the API's own origin. A
client-supplied "custom:" value is refused: the server mints those, so a stack
cannot be pointed at a file it does not own. Files follow the stack: replaced on
re-upload (including across formats, or the old one orphans), copied on clone,
removed on delete.

The one piece of plumbing worth knowing about: the icon endpoint needs the
bearer token like everything else, and an <img src> would not carry it. So
StackIcon fetches the bytes through the API client and renders the blob, keyed
on the stored value — which carries an upload timestamp precisely so a re-upload
changes the key and retires the cached image.

Covered by 22 backend tests (the value rules, byte-sniffing, the file lifecycle,
the API round-trip, and that the read-only role cannot change an icon) and 29
frontend ones for the matcher. The schema change was verified against a
hand-built pre-0.51 database: the column is added on start and existing rows
come back NULL, i.e. automatic. Not click-tested in a browser — no Docker in
this environment — so the row height the taller icon produces is unverified.

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

backend/routers/stacks.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import os
 from dataclasses import asdict
 
-from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, File, HTTPException, Query, Request, UploadFile
 from fastapi.responses import FileResponse
 from sqlmodel import Session, select
 
@@ -31,6 +31,7 @@ from services import (
     audit_service,
     auto_update_service,
     compose_service,
+    icon_service,
     notify_service,
     stack_lock_service,
     stats_service,
@@ -99,6 +100,7 @@ def _stack_summary(
         "id": stack.id,
         "name": stack.name,
         "description": stack.description,
+        "icon": stack.icon,
         "status": status,
         "service_count": total,
         "running_count": running,
@@ -137,10 +139,16 @@ def create_stack(
     stack_id = compose_service.slugify(body.name)
     if session.get(Stack, stack_id) or os.path.isdir(compose_service.stack_dir(stack_id)):
         raise HTTPException(status_code=409, detail=f"Stack '{stack_id}' already exists")
+    try:
+        icon = icon_service.normalize_choice(body.icon or "")
+    except icon_service.IconError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
     compose_service.write_compose(stack_id, body.yaml or "services:\n")
     if body.env:
         compose_service.write_env(stack_id, body.env)
-    stack = Stack(id=stack_id, name=body.name, description=body.description)
+    stack = Stack(
+        id=stack_id, name=body.name, description=body.description, icon=icon
+    )
     session.add(stack)
     session.commit()
     session.refresh(stack)
@@ -185,6 +193,7 @@ def get_stack(
         "id": stack.id,
         "name": stack.name,
         "description": stack.description,
+        "icon": stack.icon,
         "status": status,
         "yaml": compose_service.read_compose(stack_id),
         # The .env is where credentials live by convention, so it is withheld
@@ -214,6 +223,16 @@ def update_stack(
         stack.name = body.name
     if body.description is not None:
         stack.description = body.description
+    if body.icon is not None:
+        try:
+            icon = icon_service.normalize_choice(body.icon)
+        except icon_service.IconError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        # Switching to a built-in icon (or back to automatic) makes any
+        # uploaded image dead weight, so it goes with the choice.
+        if icon_service.custom_ext(stack.icon) and icon != stack.icon:
+            icon_service.remove(stack_id)
+        stack.icon = icon
     stack.updated_at = compose_service.now()
     session.add(stack)
     session.commit()
@@ -240,6 +259,7 @@ async def delete_stack(
         pass
     if delete_files:
         compose_service.delete_stack_files(stack_id)
+    icon_service.remove(stack_id)
     session.delete(stack)
     session.commit()
     audit_service.record(
@@ -257,7 +277,7 @@ def clone_stack(
     session: Session = Depends(get_session),
     user: User = Depends(require_admin),
 ) -> dict:
-    _get_stack_or_404(session, stack_id)
+    source = _get_stack_or_404(session, stack_id)
     new_id = compose_service.slugify(body.name)
     if session.get(Stack, new_id):
         raise HTTPException(status_code=409, detail=f"Stack '{new_id}' already exists")
@@ -265,7 +285,11 @@ def clone_stack(
         compose_service.clone_stack_files(stack_id, new_id)
     except compose_service.StackFileError as exc:
         raise HTTPException(status_code=409, detail=str(exc)) from exc
-    stack = Stack(id=new_id, name=body.name)
+    stack = Stack(
+        id=new_id,
+        name=body.name,
+        icon=icon_service.copy(stack_id, new_id, source.icon),
+    )
     session.add(stack)
     session.commit()
     session.refresh(stack)
@@ -276,6 +300,85 @@ def clone_stack(
     return _stack_summary(stack)
 
 
+# --------------------------------------------------------------------------- #
+# icon
+# --------------------------------------------------------------------------- #
+
+
+@router.get("/{stack_id}/icon")
+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.
+
+    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).
+    """
+    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 ""
+    return FileResponse(
+        path,
+        media_type=icon_service.content_type(ext),
+        # 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}"'},
+    )
+
+
+@router.post("/{stack_id}/icon")
+async def upload_stack_icon(
+    stack_id: str,
+    request: Request,
+    file: UploadFile = File(...),
+    session: Session = Depends(get_session),
+    user: User = Depends(require_admin),
+) -> dict:
+    """Replace a stack's icon with an uploaded image."""
+    stack = _get_stack_or_404(session, stack_id)
+    data = await file.read(icon_service.MAX_ICON_BYTES + 1)
+    try:
+        stack.icon = icon_service.store_upload(stack_id, data)
+    except icon_service.IconError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    stack.updated_at = compose_service.now()
+    session.add(stack)
+    session.commit()
+    session.refresh(stack)
+    audit_service.record(
+        session, user=user.username, action="stack.icon", target=stack_id,
+        detail=f"uploaded {file.filename or 'image'}", ip=_client_ip(request),
+    )
+    return _stack_summary(stack)
+
+
+@router.delete("/{stack_id}/icon")
+def reset_stack_icon(
+    stack_id: str,
+    request: Request,
+    session: Session = Depends(get_session),
+    user: User = Depends(require_admin),
+) -> dict:
+    """Drop any explicit choice and go back to the name-derived icon."""
+    stack = _get_stack_or_404(session, stack_id)
+    icon_service.remove(stack_id)
+    stack.icon = None
+    stack.updated_at = compose_service.now()
+    session.add(stack)
+    session.commit()
+    session.refresh(stack)
+    audit_service.record(
+        session, user=user.username, action="stack.icon", target=stack_id,
+        detail="reset to automatic", ip=_client_ip(request),
+    )
+    return _stack_summary(stack)
+
+
 # --------------------------------------------------------------------------- #
 # lifecycle
 # --------------------------------------------------------------------------- #