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 (only for 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)

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

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

Script	Command	Purpose
Seed	npm run seed	Reload curated Wikipedia data
Thumbnails migration	npm run migrate:thumbnails	Add thumbnail columns
Fetch missing images	npm run fetch-images	Backfill painting files
Fetch artist portraits	npm run fetch-artist-images	Backfill portrait files
Sync image paths	npm run sync-image-paths	Align DB paths with disk
Expand catalog	npm run expand-catalog	Add paintings from Wikipedia lists
Update influences	npm run update-influences	Refresh influence edges

Scripts under scripts/ that are not yet present locally may need to be restored from git history or re-added; core paths (seed-wikipedia.js, image-fetcher.js) are in the repository.

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.

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
Black frames in 3D gallery	No local image for painting	POST …/preload-images or npm run fetch-images; missing works show a canvas cover
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 image	Bad museum / search match	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 or extend seed data
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