Danilka/Art-gallery
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document development-first workflow with weekly prod releases.

Browse Source 
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.
This commit is contained in:
Danila Khodjaef
2026-07-06 09:58:01 +03:00
parent 9da065acbe
commit bdddadc4d6
9 changed files with 245 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/rules/dev-first-workflow.mdc
+43
View File
@@ -0,0 +1,43 @@
---
description: Default to dev for all changes; prod only when explicitly requested
alwaysApply: true
---
# Development-first workflow
**Default target is always development** unless the user explicitly names **prod** / **production**.
## What "dev" means
| Layer | Dev default |
|-------|-------------|
| Code | Edit in this repo; run `npm run dev:web` on the dev PC |
| Database | `gallery_dev` via root `.env` (`DB_NAME=gallery_dev`) |
| Data / images | `data/images/` in the repo |
| Public URL | https://devgallery.mysuperlab.netcraze.pro |
| Migrations / seeds / scripts | `npm run migrate`, `npm run seed`, etc. against **dev** |
## Production is scheduled, not daily
Prod (`gallery_prod`, TrueNAS Docker, https://gallery.mysuperlab.netcraze.pro) is updated **roughly weekly** (or when the user explicitly asks for prod):
1. Validate on dev
2. `npm run db:backup` → `npm run db:restore:prod` (if DB/data changed)
3. `npm run images:sync-to-prod` (if images changed)
4. `npm run docker:publish` (if code changed)
5. Restart **gallery-web** on TrueNAS
Do **not** edit `infra/docker/.env.prod`, run `db:restore:prod`, `images:sync-to-prod`, or `docker:publish` unless the user clearly targets prod.
## When the user says "fix", "change", or "modify"
- Assume **dev** code, **dev** DB, and **dev** data paths
- Test against devgallery or localhost
- Mention prod steps only as optional follow-up for the next release
## When the user says "prod" or "production"
- Use `gallery_prod`, `infra/docker/.env.prod`, TrueNAS compose, and prod deploy docs
- Require explicit confirmation before destructive prod operations (`db:restore:prod`, etc.)
Full operator guide: `Documentation/environments.md`
.env.example
+2 -1
View File
@@ -1,4 +1,5 @@
# Development — copy to .env (not committed)
# Development only — copy to .env (not committed). All day-to-day work uses gallery_dev.
# Promote to prod on a scheduled release (~weekly); see Documentation/environments.md
DB_HOST=192.168.10.122
DB_PORT=5432
DB_USER=gallery
Documentation/FAC.md
+10 -5
View File
@@ -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
---
Documentation/basics.md
+6 -4
View File
@@ -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
Documentation/environments.md
+27 -6
View File
@@ -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
---
Documentation/setup.md
+2
View File
@@ -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
README.md
+2
View File
@@ -75,6 +75,8 @@ Operator guide: [Documentation/environments.md](Documentation/environments.md).
## Development
**Workflow:** All changes are made and tested on **dev** (`gallery_dev`, https://devgallery.mysuperlab.netcraze.pro). Production is updated on a **scheduled release** (~weekly): promote DB/images, build/push the Docker image, restart TrueNAS. See [Documentation/environments.md](Documentation/environments.md#development-first-workflow-default).
**Public dev (Keenetic):**
```bash
infra/docker/.env.prod.example
+3 -2
View File
@@ -1,5 +1,6 @@
# Copy to infra/docker/.env.prod on TrueNAS or build PC (do not commit).
# Used by compose.prod.yaml and npm run db:migrate:prod / db:restore:prod.
# Production only — copy to infra/docker/.env.prod (do not commit).
# Used for scheduled releases: db:restore:prod, docker:publish, TrueNAS gallery-web.
# Day-to-day development uses root .env → gallery_dev.
DB_HOST=192.168.10.122
DB_PORT=5432
infra/docker/DEPLOY-truenas.md
+3 -1
View File
@@ -2,7 +2,9 @@
Production deployment for the **Express API + built Vite SPA** container. PostgreSQL stays on the host at `192.168.10.122:5432`. Public URL: **https://gallery.mysuperlab.netcraze.pro** (Keenetic → TrueNAS `:5173`, protocol to device **http**).
Production deployment for the **Express API + built Vite SPA** container. PostgreSQL stays on the host at `192.168.10.122:5432`. Public URL: **https://gallery.mysuperlab.netcraze.pro** (Keenetic → TrueNAS `:5173`, protocol to device **http**).
**Not for daily work.** Develop on dev (`gallery_dev`, https://devgallery.mysuperlab.netcraze.pro). Use this guide when **releasing** to prod (~weekly): build/push image, sync data/images if needed, restart the TrueNAS app.
See also [Documentation/environments.md](../../Documentation/environments.md#development-first-workflow-default).
## Architecture