puttaalu
434d2437bf
Add HTTP Basic auth on /upload, reading an Apache htpasswd file (bcrypt only, `htpasswd -B`) via a new -htpasswd flag. This lets nginx drop to a plain TLS-terminating reverse proxy with no auth of its own; the existing bcrypt htpasswd file is reused unchanged. auth.go: - LoadHtpasswd parses user:hash lines, keeps bcrypt entries ($2a/$2b/$2y, so Apache's $2y$ works), skips MD5/SHA/crypt with a warning. - Unknown users still pay for one bcrypt comparison against a dummy hash, so response timing can't enumerate valid usernames. - Failed attempts draw from a token-bucket limiter (x/time/rate, ~1/s, burst 10) returning 429 once drained; successful and bulk uploads never touch it. server.go guards both /upload routes (nil authenticator = passthrough for local --serve). /health stays open. Empty -htpasswd disables auth and logs a warning. module.nix: new top-level services.photogallery.htpasswdFile, delivered to the service via systemd LoadCredential (so a root-owned 0400 secret works). Removed nginx.htpasswdFile and basic_auth from the vhost. Both uploader apps already send Basic credentials, so no client change. Deps: golang.org/x/crypto/bcrypt, golang.org/x/time/rate (vendorHash bump).
209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
# photogallery
|
||
|
||
Personal static photo gallery with Atom feed and upload API. Single-user.
|
||
No database, no framework — just a Go binary that watches a directory and regenerates a static site.
|
||
An Android app in `android/` posts to the same upload API.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
content/ # images + .toml sidecars (source of truth)
|
||
public/ # generated output (served by nginx / --serve flag)
|
||
templates/ # embedded HTML templates
|
||
static/ # embedded CSS + JS
|
||
android/ # Kotlin/Compose uploader app, own flake
|
||
```
|
||
|
||
The binary does three things at once:
|
||
- Watches `content/` via fsnotify and rebuilds on any change
|
||
- Serves a multipart upload API at `POST /upload`
|
||
- In dev mode (`--serve`), also serves `public/` as static files
|
||
|
||
Routes: `GET /upload` (HTML upload form), `POST /upload` (multipart), `GET /health`.
|
||
Both `/upload` routes are gated by HTTP Basic auth when `-htpasswd` is set (see Auth); `/health` is always open.
|
||
|
||
In production nginx sits in front: serves `public/` directly, proxies `/upload` to localhost, terminates TLS. Auth is **no longer nginx's job** — the app checks credentials itself (`auth.go`), so the nginx vhost just proxies. Note `/health` is **not** proxied — nginx only forwards `location /upload`, so anything outside the box can only reach `/upload`.
|
||
|
||
## Auth
|
||
|
||
`-htpasswd <file>` points at an Apache htpasswd file — **bcrypt only**, generate
|
||
with `htpasswd -B`. Each `POST /upload` and `GET /upload` then needs HTTP Basic
|
||
credentials matching a line in that file; `GET /health` stays open. `$2y$`
|
||
(Apache) and `$2a$`/`$2b$` hashes are all accepted; non-bcrypt lines (MD5
|
||
`$apr1$`, SHA, crypt) are skipped with a warning. Empty `-htpasswd` disables
|
||
auth entirely (dev default) and logs a warning — `/upload` is then open.
|
||
|
||
Verification lives in `auth.go`: unknown users still pay for one bcrypt
|
||
comparison (against a dummy hash) so timing can't enumerate usernames, and
|
||
**failed** attempts draw from a token-bucket limiter (`golang.org/x/time/rate`,
|
||
~1/s, burst 10) that returns `429` once drained — successful and bulk uploads
|
||
never touch it. Both apps (Android, Qt desktop) already send Basic auth, so no
|
||
client change was needed. Deps: `golang.org/x/crypto/bcrypt`, `golang.org/x/time/rate`.
|
||
|
||
## Stack
|
||
|
||
- **Go** — stdlib + `BurntSushi/toml`, `fsnotify/fsnotify`, `golang.org/x/image`, `golang.org/x/crypto` (bcrypt), `golang.org/x/time` (rate)
|
||
- **Templates** — `html/template`, embedded via `embed.FS`
|
||
- **Images** — four renditions per photo: original copy, 600×600 centre-cropped square thumbnail, a 1600px-longest-side "medium" for the detail page, and a 1200px "og" for link previews. Catmull-Rom resize. Outputs are skipped when newer than the source.
|
||
- **Feed** — Atom (`encoding/xml`)
|
||
- **NixOS** — `flake.nix` + `module.nix`, exports `nixosModules.default`
|
||
|
||
## Sidecar format
|
||
|
||
```toml
|
||
caption = "Tempelhof at sunrise"
|
||
date = "2026-06-14"
|
||
tags = ["berlin", "sunrise"]
|
||
```
|
||
|
||
Missing sidecar → filename as caption, today as date. Photos sort newest first by that date.
|
||
|
||
`tags` is optional, free-text, and defines albums (see below). Tags are
|
||
normalized to lowercase on load/upload (`parseTags` in `albums.go`); a tag may
|
||
contain spaces (`"berlin trip"`), and its URL slug is derived with `sanitiseSlug`.
|
||
|
||
## Design
|
||
|
||
- Gruvbox dark hard colour scheme
|
||
- Crimson Pro (serif) for headings and captions — configurable via `-serif-family` / `-fonts-url`
|
||
- Manjari for Malayalam text (bio line), via `-ml-family`
|
||
- Two views of the same photos, both 3-column square grid → 2-column on mobile, both with infinite-scroll load-more. Page size is configurable via `-page-size` (default 60; NixOS `services.photogallery.pageSize`):
|
||
- **Timeline is the site root** (`/`, `/page/2/`, …). Photos grouped by calendar day: one ISO date heading (`2026-06-14`) + count per day, then the square grid. `groupByDay` collapses the newest-first list into consecutive same-day runs; `chunkDayGroups` packs whole days into pages targeting `pageSize`, never splitting a day across a page boundary (so appended pages never duplicate a heading — the load-more JS relies on this).
|
||
- **Grid** (`/grid/`, `/grid/page/2/`, …) is the flat square grid, linked from the profile header.
|
||
- Each timeline date heading links to a **single-day page** (`/day/<YYYY-MM-DD>/`) holding just that day's photos. `renderDayPages` writes one per `groupByDay` run; the ISO label doubles as the URL slug.
|
||
- Single photo page with sidebar and newer/older navigation
|
||
|
||
### Albums (tags)
|
||
|
||
A second grouping axis, parallel to days: an album is just a tag (`albums.go`).
|
||
`groupByTag` mirrors `groupByDay`, and `renderAlbumPages` writes a paginated
|
||
square-grid album per tag at `/album/<slug>/` (like the grid view). `/albums/`
|
||
is the index of every tag with counts; `/tags.json` is the machine-readable tag
|
||
list (`[{tag, slug, count}]`, served statically like `feed.xml`). Tags show on
|
||
each photo page and link to their album; an **Albums** link sits in the
|
||
timeline/grid header. Tags are assigned at upload via the `tags` field on
|
||
`POST /upload` (comma-separated) or by editing a sidecar's `tags`. All derived at
|
||
build time — no database.
|
||
|
||
### Link previews
|
||
|
||
Photo pages carry Open Graph + Twitter-card meta tags so a shared link unfurls
|
||
in WhatsApp, Telegram, etc. `generateOG` writes a dedicated `public/og/`
|
||
rendition — 1200px longest side, quality laddered down until under ~250 KB,
|
||
because WhatsApp drops the preview above ~300 KB and the medium rendition can
|
||
exceed that. The `og:image` URL is absolute (`{{.BaseURL}}/...`); both crawlers
|
||
ignore relative image paths, and previews only work against the deployed
|
||
`-base-url`, never `http://localhost`. `og:image:width`/`height` come from
|
||
`DecodeConfig` on the OG file, read even when the file itself was skipped as up
|
||
to date. Both platforms cache per URL — after a deploy, re-scrape via
|
||
`@webpagebot` (Telegram) or Facebook's sharing debugger (WhatsApp).
|
||
|
||
### Photo page navigation
|
||
|
||
`static/photo-nav.js` handles arrow keys and touch swipe. Both read their
|
||
destinations from the `[data-nav="newer"]` / `[data-nav="older"]` anchors the
|
||
template renders, so a photo with no sibling in that direction has nothing to
|
||
find and the gesture rubber-bands. If the script fails to load the links still
|
||
work.
|
||
|
||
Swipe left → older, right → newer, matching ArrowRight/ArrowLeft. Constraints
|
||
worth knowing before touching it:
|
||
|
||
- Swipes starting within 24px of a screen edge are ignored — that strip is the browser's own back-gesture.
|
||
- Only `pointerType === "touch"`, so desktop drag-to-save is untouched.
|
||
- Axis locks once after 10px so vertical drags stay scrolls; `touch-action: pan-y` tells the compositor the same.
|
||
- The image is wrapped in an `<a>` to the full-size original, so the click trailing a swipe is suppressed or it opens a new tab.
|
||
- `EXIT_MS` in the JS must stay in sync with the transition duration in `style.css`.
|
||
|
||
Anything added under `static/` is embedded and copied to `public/static/`
|
||
automatically — `assets.go` embeds the whole directory and `copyStatic()` walks
|
||
every entry, so new CSS/JS needs no generator change.
|
||
|
||
## Running locally
|
||
|
||
```bash
|
||
nix develop
|
||
go mod tidy
|
||
go run . --serve
|
||
# gallery: http://localhost:8080
|
||
# upload: http://localhost:8080/upload
|
||
```
|
||
|
||
## Android app
|
||
|
||
Kotlin + Jetpack Compose uploader: pick or share a photo, add caption and date, post. Credentials (HTTP Basic) are sealed with an Android Keystore AES-GCM key. See `android/README.md` for the detail.
|
||
|
||
Its own flake, deliberately separate from the root one so NixOS consumers of `nixosModules.default` don't pull the Android SDK into their lock:
|
||
|
||
```bash
|
||
cd android
|
||
nix develop
|
||
./gradlew assembleRelease # app/build/outputs/apk/release/app-release.apk
|
||
```
|
||
|
||
The server needs no changes to serve it — every gap (slug collisions, EXIF, HEIC, size caps) is closed client-side. Release builds need `android/keystore.properties`; without it the signing config is skipped and only debug builds work.
|
||
|
||
## NixOS module usage
|
||
|
||
```nix
|
||
inputs.photogallery.url = "github:youruser/photogallery";
|
||
# in modules:
|
||
inputs.photogallery.nixosModules.default
|
||
# in configuration.nix:
|
||
services.photogallery = {
|
||
enable = true;
|
||
baseURL = "https://photos.yourdomain.tld";
|
||
# bcrypt htpasswd (`htpasswd -B`); handed to the service via LoadCredential,
|
||
# so a root-owned 0400 secret is fine. Omit to leave /upload open.
|
||
htpasswdFile = "/run/secrets/photogallery-htpasswd";
|
||
nginx = {
|
||
enable = true;
|
||
domain = "photos.yourdomain.tld";
|
||
};
|
||
};
|
||
```
|
||
|
||
## Bootstrap (first nix build)
|
||
|
||
```bash
|
||
go mod tidy # generates go.sum — commit it
|
||
nix build # fails, prints correct vendorHash
|
||
# paste hash into flake.nix
|
||
nix build # succeeds
|
||
```
|
||
|
||
## Key files
|
||
|
||
| File | Purpose |
|
||
|---|---|
|
||
| `main.go` | Flags, wires generator + watcher + server |
|
||
| `generator.go` | Scans content dir, renders HTML + Atom feed, generates thumbs/mediums |
|
||
| `albums.go` | Tag parsing/normalization, `groupByTag`, album pages + `/albums/` + `/tags.json` |
|
||
| `server.go` | Upload API + optional static file serving |
|
||
| `auth.go` | htpasswd (bcrypt) HTTP Basic auth + failed-attempt rate limit for `/upload` |
|
||
| `watcher.go` | fsnotify watcher with 500ms debounce |
|
||
| `assets.go` | `//go:embed` for templates and static |
|
||
| `templates/timeline.html` | Site root: photos grouped by day, paginated |
|
||
| `templates/grid.html` | Flat square grid at `/grid/`, paginated |
|
||
| `templates/day.html` | Single-day page at `/day/<date>/` |
|
||
| `templates/album.html` | Album (tag) page at `/album/<slug>/`, paginated |
|
||
| `templates/albums.html` | Album index at `/albums/` |
|
||
| `templates/photo.html` | Single photo page, neighbour links and prefetch |
|
||
| `static/photo-nav.js` | Arrow-key and swipe navigation |
|
||
| `module.nix` | NixOS module (systemd service, tmpfiles, nginx vhost) |
|
||
| `flake.nix` | `buildGoModule` package + devShell + nixosModules |
|
||
| `android/flake.nix` | Android SDK dev shell (separate from the root flake) |
|
||
|
||
## Gotchas
|
||
|
||
- `.gitignore` patterns here must be anchored. An unanchored `photogallery` also matches the Kotlin package directory `android/app/src/main/java/ws/inflo/photogallery/` and silently swallows every source file in it.
|
||
|
||
## What's not done yet
|
||
|
||
- ActivityPub federation (planned later — start with RSS/Atom)
|
||
- Multi-image upload
|
||
- Delete/edit via UI
|
||
- Any auth beyond the app's htpasswd Basic auth on `/upload` (no sessions, no per-user scopes)
|
||
- The Android app has never been run on real hardware
|
||
- Photo-page swipe has never been tested on a real touchscreen; the iOS Safari edge-gesture interaction is the untested part
|