jaap14/contactsheet repository overview

⁠ContactSheet

A better way to look at Flickr. A standalone explorer/viewer for Flickr that fixes the things the official site gets wrong — dark backdrop, smooth grid↔image navigation, no buggy back-button state (your scroll position is preserved across the lightbox), and a layout shaped around how a photographer actually wants to scan photos.

Sibling tool to Darkroom Log⁠ — same aesthetic family (IBM Plex, dark UI).

The photo detail page surfaces EXIF, comments, fave/fave-count, location, plus collapsible "In albums" / "In groups" / "Tags" disclosures — all in one place, all in-app (album and group links route to ContactSheet's own views, not flickr.com).

Search returns matching Flickr groups alongside photos, so you can jump from a query into a community as easily as into a single image.

Source: https://github.com/jaapjan14/contactsheet⁠

⁠Quick start

services:
  contactsheet:
    image: jaap14/contactsheet:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      APP_PASSWORD: change-me
      SESSION_SECRET: generate-with-openssl-rand-base64-24
      FLICKR_API_KEY: your-flickr-api-key
      FLICKR_API_SECRET: your-flickr-api-secret
      ORIGIN: http://localhost:3000
    volumes:
      - ./data:/app/data

docker compose up -d

Open http://localhost:3000, enter APP_PASSWORD, then click sign in to Flickr to complete the OAuth dance.

⁠Getting Flickr API credentials

1. Go to https://www.flickr.com/services/api/keys/apply⁠
2. Sign in with the Flickr account whose photos you'll be browsing
3. Pick APPLY FOR A NON-COMMERCIAL KEY
4. Fill in app name + description, accept terms, submit
5. Copy the Key and Secret into FLICKR_API_KEY / FLICKR_API_SECRET

The API has an undocumented but real rate limit (~3,600 calls/hour). ContactSheet's SQLite cache absorbs most of it — most pages re-render from cache for several minutes after the first request.

⁠Configuration

⁠Volumes

⁠Tags

• latest — current release
• vX.Y.Z — pinned release

⁠What's new in v1.5.4 (since v1.1.0)

• Per-profile photo search — a search icon on a user's Photostream now scopes Flickr search to just that person's photos, matching Flickr's own profile search. Results replace the grid in place; clear the search to return to the full stream.
• Group discussions — a group's page now has a Discussions tab listing recent topics with reply counts and last-reply dates; click into a topic for the full threaded view. Signed in, you can post, edit, and delete your own topics and replies, with Flickr's own error messages surfaced cleanly and a proactive notice when a group has discussions disabled.
• Instant lightbox + streamed photo load — clicking a thumbnail opens the lightbox as an overlay immediately; the image and the social/group panels (comments, faves, "in albums/groups") stream in progressively rather than blocking the open. Closing is still a pure history.back() with your grid scroll intact.
• Sort groups by recent activity — the groups page gains an "Activity" sort that ranks a user's groups by most-recent activity, with a relative "active 3h ago" badge per row.
• Auth-aware cache — signed and anonymous responses for the same endpoint are now cached separately, so a private group's signed values can no longer be poisoned by an anonymous fetch (or vice-versa).
• Graceful Flickr-outage handling — a Flickr 5xx "panda" page or 429 rate-limit now degrades to a retryable state instead of a hard 500, and never dumps Flickr's HTML error page into your logs.
• Helpful "user not found" page — typing a multi-word display name no longer dead-ends; the page explains what ContactSheet can resolve (URL, path-alias, NSID) and one-clicks you to Flickr's people search.
• Smaller polish: accent-colored commenter names, a photo-zoom double-click fix, and a favicon.ico for legacy clients.

⁠Highlights

• 7-tab user view: photostream · about · albums · faves · galleries · groups · camera roll · stats
• Lightbox with EXIF, comments, fave/fave-count, "in albums/groups" disclosures, pinch/ctrl-wheel zoom
• High-res progressive load — preview paints instantly, X-Large 6K then Original swap in on fullscreen
• Combined search: free text + user + tags + sort, also surfaces matching Flickr groups in the same result set
• Group discussions — browse topics and replies, and post/edit/delete your own when signed in
• Background notifications poller — new faves, comments, and Explore hits, dedup'd by composite source ID, surfaced in an in-app bell
• SQLite response cache (better-sqlite3) wraps every Flickr API call with per-endpoint TTLs
• Hand-rolled OAuth 1.0a (no oauth dep) — HMAC-SHA1 signer, single-user token store
• App-password gate fronts every route with HMAC-signed session cookie + per-request CSP nonce