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)
PORT	API listen port (default 3001)
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    # apply db/schema.sql
npm run seed       # eras, movements, artists, paintings, influences

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 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
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 ..

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 server	API + static SPA on PORT
npm run dev:server	API with nodemon reload
npm run dev:client	Vite dev server on :5173
npm run dev	Alias for server

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

cd client && npm run build && cd ..
npm run server

Open http://localhost:3001 (or your configured PORT).

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	Backfill portrait files (if present)
npm run sync-image-paths	scripts/sync-image-paths.js	Align DB paths with disk (if present)
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 find-duplicates	scripts/find-duplicate-paintings.js	Report duplicate and near-duplicate painting 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:

• image-fetcher.js — Wikimedia / museum image resolution
• 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
• migrate-checkup-flags.js — checkup workflow columns
• regenerate-thumbnails.js, audit-painting-images.js

These are referenced in package.json but may need to be restored from git history if missing locally: seed-wikipedia.js, fetch-artist-images.js, sync-image-paths.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 npm run setup against your Postgres instance, then the post-seed steps above.

Troubleshooting

Symptom	Likely cause	Fix
Empty timeline	DB not seeded	npm run seed
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
Artist hall has only 1–2 paintings	Catalog not expanded	npm run expand-catalog; extend famous-paintings-data.js
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 painting_influences edges for artist	npm run update-influences
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
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
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