forked from sagnik/Project_Velocity
144 lines
3.7 KiB
Markdown
144 lines
3.7 KiB
Markdown
# Velocity Local Dev Snapshot
|
|
|
|
This document defines the correct way to work against a local copy of the current Velocity backend state without polluting Git and without guessing whether a backend-only change will work in production.
|
|
|
|
## Why This Exists
|
|
|
|
Project Velocity now depends on live PostgreSQL-backed surfaces and runtime state that cannot be validated reliably from frontend-only local development.
|
|
|
|
Examples:
|
|
|
|
- operator identity and profile hydration
|
|
- CRM-backed Sentinel client selection
|
|
- Oracle Canvas data access and sharing
|
|
- verified team-account lists for share flows
|
|
|
|
The correct solution is a repeatable local snapshot workflow.
|
|
|
|
## Design Rule
|
|
|
|
Local runtime copies must never be committed.
|
|
|
|
Everything produced by this workflow lives under gitignored paths:
|
|
|
|
- `.local-dev/`
|
|
- `runtime-snapshots/`
|
|
- `local-dev-bundles/`
|
|
|
|
## Bundle Shape
|
|
|
|
The Linux-origin export bundle contains:
|
|
|
|
- `backend.env.export`
|
|
- `velocity.dump`
|
|
- `restore.instructions.txt`
|
|
|
|
This is intentionally minimal. It gives local developers what they need to stand up a local database-backed verification surface without pushing runtime state into the repository.
|
|
|
|
## Export From Linux Box
|
|
|
|
Run this on the Linux-origin host:
|
|
|
|
```bash
|
|
cd /opt/desineuron-velocity-site/repo
|
|
bash scripts/export_velocity_local_bundle.sh
|
|
```
|
|
|
|
This creates a tarball in `/tmp` named like:
|
|
|
|
```text
|
|
/tmp/velocity-local-bundle-YYYYmmdd-HHMMSS.tar.gz
|
|
```
|
|
|
|
## Import On Windows Dev Machine
|
|
|
|
1. Copy the tarball to the Windows machine.
|
|
2. Extract it under:
|
|
|
|
```text
|
|
Project_Velocity/.local-dev/source-bundles/<bundle-name>/
|
|
```
|
|
|
|
3. Run:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\import_velocity_local_bundle.ps1
|
|
```
|
|
|
|
This will:
|
|
|
|
- copy the exported env snapshot into `.local-dev/backend/.env.local`
|
|
- copy the PostgreSQL dump into `.local-dev/db/velocity.dump`
|
|
- generate a local Docker Compose file for PostgreSQL
|
|
- generate a restore script
|
|
|
|
## Restore Local Database
|
|
|
|
After import, run:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\.local-dev\db\restore_local_snapshot.ps1
|
|
```
|
|
|
|
This restores the dump into a local PostgreSQL container on:
|
|
|
|
- host: `127.0.0.1`
|
|
- port: `54329`
|
|
- db: `velocity_local`
|
|
- user: `velocity_local`
|
|
- password: `velocity_local`
|
|
|
|
## Local Backend Wiring
|
|
|
|
The backend expects these env keys:
|
|
|
|
- `VELOCITY_DB_HOST`
|
|
- `VELOCITY_DB_PORT`
|
|
- `VELOCITY_DB_NAME`
|
|
- `VELOCITY_DB_USER`
|
|
- `VELOCITY_DB_PASSWORD`
|
|
- `DATABASE_URL`
|
|
- `CORS_ORIGINS`
|
|
- `VELOCITY_ASSET_DIR`
|
|
- `JWT_SECRET_KEY`
|
|
|
|
The exported env snapshot provides the production-shaped variable names. For local verification, point the DB values to the local PostgreSQL container rather than the production database.
|
|
|
|
## Create A Zip For Sayan And Sourik
|
|
|
|
Once `.local-dev/` is hydrated locally, run:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\package_velocity_local_bundle.ps1
|
|
```
|
|
|
|
This creates a gitignored zip under:
|
|
|
|
```text
|
|
Project_Velocity/local-dev-bundles/
|
|
```
|
|
|
|
That zip is the correct handoff artifact for teammate local verification.
|
|
|
|
## What This Solves
|
|
|
|
This workflow allows local verification of:
|
|
|
|
- real account-backed login flows
|
|
- profile name/avatar hydration
|
|
- share-recipient lookup
|
|
- Sentinel CRM client selection
|
|
- Oracle-backed DB reads
|
|
|
|
## What It Does Not Solve By Itself
|
|
|
|
This does not automatically fix backend bugs.
|
|
|
|
If Oracle still returns `500` locally after restoring the snapshot, that is now a real reproducible backend issue rather than a blind production-only guess.
|
|
|
|
## Current Constraint
|
|
|
|
The current machine cannot SSH into the Linux box because the host is configured for publickey auth and this workstation is not authorized yet.
|
|
|
|
That means the export step must currently be triggered from a machine or shell that already has valid SSH/key access to the Linux-origin host.
|