Art-gallery/Documentation/setup.md

Art Gallery — setup and operations

Prerequisites

• Node.js 20+
• PostgreSQL reachable from the app host
• Network access to Wikipedia / Wikimedia (for biographies, seeding, and on-demand image fetch)

Environment

Copy the example file and fill in credentials:

cp .env.example .env

Variable	Description
DB_HOST	PostgreSQL host
DB_PORT	Port (default 5432)
DB_USER	Database user
DB_PASSWORD	Database password
DB_NAME	Database name (gallery_dev for dev; prod uses gallery_prod)
PORT	API listen port (3451 for dev:web; prod container uses 5173)
HOST	Bind address (default 0.0.0.0 — required for LAN access)
PUBLIC_URL	Public URL (dev: https://devgallery.mysuperlab.netcraze.pro; prod: https://gallery.mysuperlab.netcraze.pro)
TRUST_PROXY	Set to true when behind nginx/reverse proxy (honours X-Forwarded-*)
IMAGE_DIR	Root for cached images (default ./data/images)

Optional script tuning:

Variable	Used by	Description
MIN_PAINTINGS	expand-catalog	Minimum paintings per artist (default 6)
FETCH_MAX_WAIT_SEC	fetch-images	Max seconds per painting in batch runs (default 10)

.env is git-ignored; never commit passwords.

Install

npm install
cd client && npm install && cd ..

Database bootstrap

One-shot setup (migrate + seed):

npm run setup

Or step by step:

npm run migrate    # db/schema.sql + db/migrate-*.sql via server/migrate.js
npm run seed       # eras, movements, artists, flagship paintings (one per artist)

npm run migrate is safe to re-run on existing databases (uses IF NOT EXISTS / ADD COLUMN IF NOT EXISTS).

If migration fails with permission errors, grant schema rights to the app user first (see DB_structure.md).

Recommended post-seed steps

After a fresh seed, run these to match a fully populated local install:

npm run sync-image-paths           # import paintings from data/images/paintings/ (clone with image files)
npm run fetch-artist-images        # link local portraits or download from Wikipedia
npm run fetch-artist-bios          # bio_short / bio_full from Wikipedia
npm run expand-catalog             # famous works for artists below MIN_PAINTINGS
npm run update-influences          # painting influence graph for detail view + hall exits
npm run migrate:checkup-flags      # optional: review/fixed flags for Checkup page (paintings)
npm run migrate:artist-checkup-flags  # optional: same flags for artist portraits (bio debug)
npm run migrate:painting-annotations  # optional: art-history notes table
npm run update-painting-annotations   # optional: load curated notes (+ --wikipedia for Wikipedia intros)
npm run fetch-images -- --limit=50                # random sample; 10s max per painting (default)
npm run fetch-images -- --limit=50 --max-wait=120 # same batch size, longer lookup per work
cd client && npm run build && cd ..

Order matters: sync-image-paths should run when the repo already contains painting files under data/images/paintings/ but the database only has one flagship work per artist (typical after npm run setup on a clone). update-influences is required for Influenced By / Influenced panels and golden lamps in the 3D hall — seed does not insert influence edges.

Image fetch can take hours if you run it for the entire catalog. The first line of each run reports Missing local files: N. Use npm run fetch-images -- --limit=N for random batches (10s per painting by default), --artist="…" for one artist in catalog order, or on-demand resolution when viewing a painting in the detail view.

Run

Command	Purpose
npm run dev:web	Public dev stack — Vite :5173, API :3451 (Keenetic → devgallery…)
npm run docker:publish	Build + push prod image to Gitea
npm run images:sync-to-prod	Copy data/images/ → TrueNAS via SMB Gallery share
npm run images:sync-from-prod	Copy prod images → dev repo
npm run db:sync-from-prod	Clone gallery_prod → gallery_dev
npm run db:backup / db:restore:prod	Dev backup / promote to prod
npm run build	Build production SPA into client/dist
npm run start	API + static SPA on HOST:PORT
npm run start:prod	Build client, then start server
npm run server	Alias for start
npm run dev:server	API with nodemon reload (local :3520 / :5173 workflow)
npm run dev:client	Vite dev server on :5173
npm run dev	Alias for start

See environments.md for dev/prod URLs, database split, Docker deploy, and sync commands.

Production frontend: build the client, then start the server:

npm run build
        # or: cd client && npm run build && cd ..
npm run start

Open http://localhost:5173 (Vite) or http://localhost:3451 (API only).

Production deployment

Production runs as gallery-web on TrueNAS at https://gallery.mysuperlab.netcraze.pro (Keenetic → :5173). Full guide: environments.md and infra/docker/DEPLOY-truenas.md.

Access	URL
Production (Keenetic)	https://gallery.mysuperlab.netcraze.pro
Development (Keenetic)	https://devgallery.mysuperlab.netcraze.pro
LAN direct (prod container)	http://192.168.10.122:5173
LAN direct (dev PC)	http://192.168.10.70:5173

Quick deploy checklist:

1. One-time DB split in pgAdmin on dev PC: db/split-dev-prod-pgadmin.sql
2. Dev .env → DB_NAME=gallery_dev, PORT=3451, PUBLIC_URL=https://devgallery.mysuperlab.netcraze.pro
3. net use \\192.168.10.122\Gallery → npm run images:sync-to-prod
4. npm run docker:publish → TrueNAS Custom App from infra/docker/compose.truenas.yaml
5. Keenetic: both domains → :5173, protocol to device http, correct IP per environment

Legacy deployment (optional)

Node on the dev PC at :3520 with nginx → Vite :5173 is superseded by TrueNAS Docker prod and npm run dev:web for public dev. See deploy/nginx-gallery.conf and deploy/gallery.service only if you need a local nginx/systemd setup.

Maintenance scripts

Command	Script	Purpose
npm run seed	scripts/seed-wikipedia.js	Reload curated Wikipedia data
npm run fetch-artist-bios	scripts/fetch-artist-bios.js	Wikipedia lead sections → bio_short / bio_full
npm run fetch-artist-bios -- --force	↑	Refresh bios even when already set
npm run expand-catalog	scripts/expand-paintings.js	Insert famous works from famous-paintings-data.js
npm run expand-catalog -- --fetch-images	↑	Also download images for new rows (slow)
npm run fetch-images	scripts/fetch-missing-images.js	Search Wikipedia, Commons, museums for missing files
npm run search-missing-paintings	↑ (alias)	Same as fetch-images
npm run fetch-images -- --artist="Name"	↑	Limit to one artist (catalog order)
npm run fetch-images -- --limit=50	↑	Random sample of N missing paintings
npm run fetch-images -- --limit=250	↑	Larger random batch (processes min(N, missing count))
npm run fetch-images -- --limit=50 --max-wait=120	↑	Random batch; 120s cap per painting
npm run fetch-images -- --discover-only --limit=20	↑	Fix wikipedia_title via search only
npm run regenerate-thumbnails	scripts/regenerate-thumbnails.js	Rebuild all thumbs from full local files
npm run audit-painting-images	scripts/audit-painting-images.js	List thumb/full aspect-ratio mismatches
npm run migrate:thumbnails	db/migrate-thumbnails.sql	Add thumbnail columns
npm run fetch-artist-images	scripts/fetch-artist-images.js	Download portraits or link existing files under data/images/portraits/
npm run fetch-artist-images -- --force	↑	Re-fetch even when portrait_path is set
npm run sync-image-paths	scripts/sync-image-paths.js	Link image_path / thumbnail_path and import missing painting rows from disk
npm run sync-image-paths -- --dry-run	↑	Report only, no DB writes
npm run migrate:influence-sources	scripts/migrate-influence-sources.js	Create painting_influence_sources + backfill legacy edges
npm run migrate:checkup-flags	scripts/migrate-checkup-flags.js	Add checkup_checked / checkup_fixed on paintings
npm run migrate:artist-checkup-flags	scripts/migrate-artist-checkup-flags.js	Add checkup_checked / checkup_fixed on artists (bio debug)
npm run migrate:painting-annotations	scripts/migrate-painting-annotations.js	Create painting_annotations table
npm run migrate:artist-palette	scripts/migrate-artist-palette.js	Add palette_metadata JSONB on artists
npm run import-painter-palette	scripts/import-painter-palette.js	Enrich artists + influence links from Inputs/PainterPalette.csv
npm run analyze-painter-palette	scripts/analyze-painter-palette.js	Report CSV ↔ gallery artist name matches
npm run export-paintings	scripts/export-paintings-csv.js	Write Output/paintings.csv (artist, painting, year)
npm run update-painting-annotations	scripts/update-painting-annotations.js	Load curated notes from painting-annotations-data.js
npm run update-painting-annotations -- --wikipedia	↑	Add intro sentences from each work’s Wikipedia page
npm run update-painting-annotations -- --wikipedia --wiki-delay=3000	↑	Slower Wikipedia pass when rate-limited (429)
npm run find-duplicates	scripts/find-duplicate-paintings.js	Report duplicate and near-duplicate painting rows
npm run audit-influence-duplicates	scripts/audit-influence-duplicates.js	Report mirrored legacy/sources edges and duplicate influence rows
npm run update-influences	scripts/update-influences.js	Insert influence links (painting / artist / movement) from art-influences-data.js
npm run update-influences -- --fetch-images	↑	Also download images for newly created works
npm run update-influences -- --discover	↑	Curated pass + web discovery (Wikipedia, Wikidata, Met, art-history sites)
npm run discover-influences	update-influences.js --discover-only	Discovery pass only

Scripts in the repository

These are checked in and maintained:

• seed-wikipedia.js, seed-catalog-data.js — initial catalog (npm run seed)
• image-fetcher.js — Wikimedia / museum image resolution
• fetch-artist-images.js — artist portrait download / disk linking
• sync-image-paths.js — import paintings and align paths from data/images/paintings/
• fetch-artist-bios.js — artist biographies
• expand-paintings.js + famous-paintings-data.js — catalog expansion
• update-influences.js + art-influences-data.js — influence graph (paintings, artists, movements)
• influence-discovery.js + influence-resolver.js — web discovery and polymorphic source resolution
• fetch-missing-images.js — batch image backfill
• find-duplicate-paintings.js — duplicate catalog audit
• audit-influence-duplicates.js — influence graph duplicate / mirror audit
• painter-palette-lib.js, import-painter-palette.js, migrate-artist-palette.js, analyze-painter-palette.js — PainterPalette CSV integration
• export-paintings-csv.js — catalog CSV export to Output/
• migrate-checkup-flags.js — checkup workflow columns (paintings)
• migrate-artist-checkup-flags.js — checkup workflow columns (artist portraits)
• migrate-painting-annotations.js, update-painting-annotations.js, painting-annotations-data.js — art-history notes on painting detail
• regenerate-thumbnails.js, audit-painting-images.js

See data-and-images.md for pipeline details and override maps.

Remote repository

Gitea: Danilka/Art-gallery

git clone https://gitea.mysuperlab.netcraze.pro/Danilka/Art-gallery.git

After clone: copy .env.example → .env, install dependencies, run one-time DB split, then post-seed steps. Deploy: environments.md.

Troubleshooting

Symptom	Likely cause	Fix
Empty timeline	DB not seeded	npm run seed
502 / 504 on public URL	Keenetic rule wrong (IP, port, or https to device)	Dev → 192.168.10.70:5173; prod → 192.168.10.122:5173; protocol http — see environments.md
503 on public URL	Dev servers not running	npm run dev:web (or dev:server + dev:client for local HMR)
manifest unknown on TrueNAS deploy	Image not in Gitea	npm run docker:publish on dev PC first
500 on all /api/*	Wrong .env or Postgres down	Check connection, logs
“Biographical information not yet available”	Bios not fetched	npm run fetch-artist-bios
Placeholder portraits on timeline	portrait_path not set	npm run fetch-artist-images
Artist hall has only 1–2 paintings	DB not expanded / disk not imported	npm run sync-image-paths then npm run expand-catalog; extend famous-paintings-data.js
Movement flow shows “Loading art history…” repeatedly	Stale client refetching on every pan/zoom	Pull latest client; timeline loads catalog once — hard-refresh
Movement flow slow on first load	Large artist payload	Client uses GET /api/artists?timeline=1 (no full bios); rebuild client
Movement flow zoom sluggish / dead over portraits	Stale client build	Rebuild client — wheel uses capture listener + interaction-mode rendering; hard-refresh
Timeline year labels overlap when zoomed out	Stale client	Rebuild client — chooseTimelineTickInterval() adapts step to span and bar width
Black frames / canvas covers in 3D gallery	No local image for painting	npm run fetch-images -- --limit=50 or --artist="…"; then POST …/preload-images
Many ⏱ timeout lines in fetch batch	Default 10s cap too short for hard works	--max-wait=120 or raise FETCH_MAX_WAIT_SEC
White/grey flicker on frames	Texture loading or z-fighting with wall	Rebuild client (cd client && npm run build); ensure latest VirtualGallery.tsx
Wrong painting in 3D gallery frame	Stale or mismatched thumbnail file	npm run regenerate-thumbnails; gallery prefers full image_path
Wrong painting image (fetch)	Bad museum / search match on first download	Add entry to DIRECT_IMAGE_OVERRIDES in scripts/image-fetcher.js, re-fetch file
Empty exit navigation lists	No influence edges for artist	npm run update-influences; check painting_influence_sources
Empty Influenced By / Influenced on painting detail	No edges for that work	npm run migrate:influence-sources then npm run update-influences; extend art-influences-data.js or run --discover
Same work listed twice under Influenced	Stale server merging legacy + sources tables	Restart server; API reads painting_influence_sources only — run npm run audit-influence-duplicates to verify DB
No golden lamps above frames in 3D hall	Stale API process or no influence edges	Restart server after API changes; run npm run update-influences
Default Vite page instead of gallery	client/dist missing or stale	cd client && npm run build
Permission denied creating tables	gallery user lacks CREATE	Run admin grants, then migrate
Wikipedia API rate limit during fetch	Too many requests in a row	Wait and re-run; scripts retry with backoff
Checkup Reviewed toggle returns 404	Stale server process missing new routes	Restart npm run dev after pulling API changes
Debug More / Clear / Upload / Remove entry returns 404	Stale server process	Restart npm run start or npm run dev:server; routes in server/index.js + server/image-service.js
Debug Remove entry — button stuck or missing on next painting	Stale client build	cd client && npm run build; hard-refresh — detail view remounts per painting id
Debug Upload returns 413 Payload Too Large	Base64 JSON exceeds body limit	Server allows 20 MB JSON / 15 MB decoded image; compress file or resize before upload
No art-history notes on painting detail	Annotations not migrated or loaded	npm run migrate:painting-annotations then npm run update-painting-annotations
Fix it fails with read ECONNRESET	Remote host dropped connection	Restart server; client sends searchUrl / source; retry or use Commons URL in overrides
Fixed image not shown in 3D gallery	Stale gallery session or cached texture	Rebuild client; fix updates session + ?v= revision — use Back to Gallery (not browser back)
Frame still black after Checked	Gallery session not synced	Re-enter hall or toggle debug Checked from detail with gallery open behind overlay
Duplicate works in gallery / timeline	Double import or variant Wikipedia titles	npm run find-duplicates; merge or delete spare rows manually
Failed to load movement gallery / Cannot GET /api/movements/:id/gallery	Stale server process missing route	Restart npm run dev or npm run dev:server after pulling API changes
Movement gallery shows generic cream walls	Stale client build	cd client && npm run build; hard-refresh browser
Windows overlap paintings in movement wing	Stale client	Rebuild client — windows are placed only on side walls in gaps between frames
Influence thumbnails cropped on painting detail	Stale client build	npm run build — panels use object-fit: contain for full image