Document development-first workflow with weekly prod releases.

Default all day-to-day work to gallery_dev and devgallery; add Cursor rule and update docs, env examples, and deploy guide for scheduled prod promotion.
2026-07-06 09:58:01 +03:00
parent 9da065acbe
commit bdddadc4d6
9 changed files with 245 additions and 166 deletions
@@ -2,6 +2,8 @@

 Quick cheat sheet for daily operations. All `npm` commands run from the **repository root** unless noted.

+**Default target: dev.** Day-to-day commands use `gallery_dev`, repo `data/images/`, and https://devgallery.mysuperlab.netcraze.pro. Prod (`gallery_prod`, Docker, `docker:publish`) is for **scheduled releases** (~weekly) — see [Promote dev → prod](#promote-dev--prod-scheduled-release) below.
+
 **Environments:**

 | | Dev | Prod |
@@ -283,14 +285,17 @@ Expect JSON with `min_year` / `max_year`. HTML shell only from `curl` on `/` is

 ---

-## Promote dev → prod (checklist)
+## Promote dev → prod (scheduled release)

-1. `npm run db:backup`
-2. Test on https://devgallery.mysuperlab.netcraze.pro
-3. `npm run db:restore:prod -- --file db/DataBackup/gallery_dev_data_....txt`
-4. `npm run images:sync-to-prod`
+~Weekly (or when explicitly releasing to prod). Not part of daily dev.
+
+1. Test on https://devgallery.mysuperlab.netcraze.pro
+2. `npm run db:backup`
+3. `npm run db:restore:prod -- --file db/DataBackup/gallery_dev_data_....txt` (if DB/catalog changed)
+4. `npm run images:sync-to-prod` (if images changed)
 5. `npm run docker:publish` (if code changed)
 6. Restart **gallery-web** on TrueNAS
+7. Verify https://gallery.mysuperlab.netcraze.pro

 ---

@@ -80,11 +80,9 @@ Gallery/

 ## Runtime modes

-### Production (TrueNAS Docker)
+**Default:** develop and test on **dev** (`gallery_dev`, devgallery URL). **Production** is updated on a scheduled release (~weekly), not on every edit. See [environments.md — Development-first workflow](environments.md#development-first-workflow-default).

-Production runs in **`gallery-web`** on TrueNAS port **5173**, database **`gallery_prod`**, public URL **https://gallery.mysuperlab.netcraze.pro**. Images: `/mnt/BasePool/Applications/Gallery/data/images` (SMB share **`Gallery`**). See [environments.md](environments.md).
-
-### Public development (`dev:web`)
+### Public development (`dev:web`) — primary

 ```bash
 npm run dev:web   # Vite :5173 + API :3451 — https://devgallery.mysuperlab.netcraze.pro
@@ -92,6 +90,10 @@ npm run dev:web   # Vite :5173 + API :3451 — https://devgallery.mysuperlab.net

 Uses database **`gallery_dev`** on the same PostgreSQL host.

+### Production (TrueNAS Docker) — scheduled releases
+
+Production runs in **`gallery-web`** on TrueNAS port **5173**, database **`gallery_prod`**, public URL **https://gallery.mysuperlab.netcraze.pro**. Images: `/mnt/BasePool/Applications/Gallery/data/images` (SMB share **`Gallery`**). Deploy via `npm run docker:publish` and the promote checklist in [environments.md](environments.md).
+
 ### Production-style single process (local)

 ```bash
@@ -9,6 +9,23 @@ Gallery uses **one PostgreSQL server** on TrueNAS (`192.168.10.122`) with **two

 ---

+## Development-first workflow (default)
+
+**All day-to-day work happens on dev.** Code edits, database changes, catalog updates, image fixes, migrations, and testing use **`gallery_dev`**, the repo’s **`data/images/`**, and **https://devgallery.mysuperlab.netcraze.pro** (or `http://localhost:5173` on the dev PC).
+
+Production is **not** updated on every change. Promote to prod on a **regular cadence** (typically about once a week) or when you explicitly decide to release:
+
+| Phase | Where | What |
+|-------|-------|------|
+| **Daily** | Dev PC + `gallery_dev` | Feature work, fixes, seed/migrate, curator edits, image pipeline |
+| **Release** | Dev PC → TrueNAS | Backup dev → restore prod DB (if data changed) → sync images → `docker:publish` → restart **gallery-web** |
+
+Unless a task explicitly says **prod** or **production**, assume the target is **dev** — including when asking an assistant to change, fix, or modify code, data, or the database.
+
+**Never** point the dev PC `.env` at `gallery_prod`. Prod-only files (`infra/docker/.env.prod`, `db:restore:prod`, `images:sync-to-prod`) are for scheduled releases, not routine development.
+
+---
+
 ## Where to run what (quick reference)

 | Step | Machine | Interface | Privilege | What |
@@ -286,15 +303,19 @@ See also [Drunkmeyou gitea-https-keenetic-npm-setup.md](../../Drunkmeyou/Documen

 ---

-## Promote dev → prod
+## Promote dev → prod (scheduled release)
+
+Run this when you are ready to ship dev to production — **not** after every small change. Typical cadence: **about once a week**.

 **Where:** Dev PC unless noted

-1. `npm run db:backup`
-2. Test on https://devgallery.mysuperlab.netcraze.pro
-3. `npm run db:restore:prod -- --file db/DataBackup/gallery_dev_data_....txt` (type `yes`)
-4. `npm run images:sync-to-prod`
-5. **TrueNAS Web UI** → restart **gallery-web** (or `npm run docker:publish` if code changed)
+1. Finish and test on https://devgallery.mysuperlab.netcraze.pro
+2. `npm run db:backup`
+3. `npm run db:restore:prod -- --file db/DataBackup/gallery_dev_data_....txt` (type `yes`) — skip if only code changed and prod DB should stay as-is
+4. `npm run images:sync-to-prod` — skip if no new/changed images
+5. `npm run docker:publish` — required when application code changed
+6. **TrueNAS Web UI** → restart **gallery-web**
+7. Verify https://gallery.mysuperlab.netcraze.pro

 ---

@@ -8,6 +8,8 @@

 ## Environment

+**Development-first:** The root `.env` is for **dev only** (`DB_NAME=gallery_dev`). All routine work — code, migrations, seeds, image scripts, curator edits — targets dev. Production uses `infra/docker/.env.prod` and TrueNAS; promote on a scheduled release (~weekly), not after every change. See [environments.md — Development-first workflow](environments.md#development-first-workflow-default).
+
 Copy the example file and fill in credentials:

 ```bash