# 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:

```bash
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

```bash
npm install
cd client && npm install && cd ..
```

## Database bootstrap

One-shot setup (migrate + seed):

```bash
npm run setup
```

Or step by step:

```bash
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](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:

```bash
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](https://gitea.mysuperlab.netcraze.pro/Danilka/Art-gallery)

```bash
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 |