Merge branch 'master' of https://git.atmata-group.com/ATMATA/zerp

DEVELOPER_STAGING_DEPLOY.md

@@ -0,0 +1,174 @@
+# Staging deploy guide (for developers)
+
+This is the **same workflow** the team uses for staging: work locally, push to Git, **sync your project folder to the server with rsync**, then **rebuild Docker on the server**. Pushing to Git alone does not update the live staging site.
+
+**Staging URL:** https://zerp.atmata-group.com/
+
+**Server project path:** `/root/z_crm` (confirm with your lead if different)
+
+---
+
+## 1. What you need from your lead
+
+| Item | Purpose |
+|------|---------|
+| **Staging server address** (IP or hostname) | For SSH and rsync |
+| **SSH login** (e.g. `root` or another user) | Remote shell and file sync |
+| **SSH key or password** | Prefer **SSH keys** (`ssh-copy-id`) so you are not typing a password on every deploy |
+
+You do **not** need Node.js **on the server**. Docker runs `npm ci` and `npm run build` inside the containers.
+
+---
+
+## 2. One-time setup on your laptop
+
+1. **Clone** the same Git repo you commit to, and use that folder as your working copy.
+2. **Test SSH:**
+   ```bash
+   ssh YOUR_USER@YOUR_SERVER_HOST
+   ```
+   Exit with `exit` once you see a shell.
+3. **Install rsync** if needed (macOS and most Linux distros include it).
+
+---
+
+## 3. Standard deploy (every time you want staging updated)
+
+Run these from your **project root** (the folder that contains `frontend/`, `backend/`, and `docker-compose.yml`).
+
+### Step 1 — Get the code you want on Git
+
+```bash
+git pull origin master
+```
+
+Resolve any conflicts, then make sure your changes are **committed and pushed**:
+
+```bash
+git push origin master
+```
+
+(Use your team’s branch name if staging tracks something other than `master`.)
+
+### Step 2 — Build locally (recommended)
+
+Catches errors before you touch the server:
+
+```bash
+cd frontend && npm run build && cd ../backend && npm run build && cd ..
+```
+
+If either build fails, fix the problem and repeat before continuing.
+
+### Step 3 — Sync files to the server (rsync)
+
+From the **project root**:
+
+```bash
+rsync -avz --delete \
+  --exclude 'node_modules' \
+  --exclude '.git' \
+  --exclude '.next' \
+  --exclude '.env' \
+  ./ YOUR_USER@YOUR_SERVER_HOST:/root/z_crm/
+```
+
+- **`./`** — trailing slash means “contents of this folder”; destination is `/root/z_crm/`.
+- **`--delete`** — removes files on the server that no longer exist in your tree (keeps server tree aligned with yours). **Excluded paths are not deleted** from the server by default when you use `--exclude` (rsync does not remove excluded remote files unless you add `--delete-excluded`, which you should **not** use here).
+- **`.env` must stay excluded** so you do **not** overwrite the server’s database URL and secrets. The server keeps its existing `/root/z_crm/.env`.
+
+Replace `YOUR_USER` and `YOUR_SERVER_HOST` with what your lead gave you.
+
+### Step 4 — Rebuild Docker on the server
+
+Either open an SSH session and run the commands, or run them in one shot:
+
+**Option A — SSH in, then commands**
+
+```bash
+ssh YOUR_USER@YOUR_SERVER_HOST
+cd /root/z_crm
+docker-compose down
+docker-compose build --no-cache frontend backend
+docker-compose up -d
+docker-compose ps
+```
+
+**Option B — One line from your laptop**
+
+```bash
+ssh YOUR_USER@YOUR_SERVER_HOST 'cd /root/z_crm && docker-compose down && docker-compose build --no-cache frontend backend && docker-compose up -d && docker-compose ps'
+```
+
+You should see `zerp_postgres` (healthy), `zerp_backend`, and `zerp_frontend` up.
+
+### Step 5 — Quick check
+
+Open https://zerp.atmata-group.com/ and do a hard refresh if the UI looks cached (`Cmd+Shift+R` / `Ctrl+Shift+R`).
+
+If the API or login fails:
+
+```bash
+ssh YOUR_USER@YOUR_SERVER_HOST 'cd /root/z_crm && docker-compose logs backend --tail 80'
+```
+
+---
+
+## 4. If the backend will not start (database / Prisma)
+
+The server relies on **`/root/z_crm/.env`** (not in Git) for `DATABASE_URL` and related settings. If that file is missing or wrong, ask your lead to fix or restore it **once**; your normal deploy should **never** sync your local `.env` over it (keep the `--exclude '.env'` on rsync).
+
+---
+
+## 5. Database migrations
+
+The backend container runs **`npx prisma migrate deploy`** when it starts. After you deploy code that includes new Prisma migrations, a normal **`docker-compose up -d`** after rebuild applies them automatically.
+
+---
+
+## 6. Optional: rebuild all services (slower)
+
+Usually you only need **frontend** and **backend** images. To rebuild everything defined in `docker-compose.yml`:
+
+```bash
+ssh YOUR_USER@YOUR_SERVER_HOST 'cd /root/z_crm && docker-compose down && docker-compose build --no-cache && docker-compose up -d'
+```
+
+Postgres **data** stays on the Docker volume unless someone removes volumes on purpose.
+
+---
+
+## 7. Alternative: Git pull **on** the server (only if `.git` exists there)
+
+Some teams keep a full clone on the server. If `/root/z_crm/.git` exists **and** the server can reach your Git remote, you can skip rsync and run:
+
+```bash
+ssh YOUR_USER@YOUR_SERVER_HOST
+cd /root/z_crm
+git pull origin master
+docker-compose down
+docker-compose build --no-cache frontend backend
+docker-compose up -d
+```
+
+If there is **no** `.git` on the server (typical when deploys have always been rsync), use **section 3** only.
+
+---
+
+## 8. Copy-paste cheat sheet (replace user/host)
+
+```bash
+# From project root, after git push:
+cd frontend && npm run build && cd ../backend && npm run build && cd ..
+
+rsync -avz --delete \
+  --exclude 'node_modules' \
+  --exclude '.git' \
+  --exclude '.next' \
+  --exclude '.env' \
+  ./ YOUR_USER@YOUR_SERVER_HOST:/root/z_crm/
+
+ssh YOUR_USER@YOUR_SERVER_HOST 'cd /root/z_crm && docker-compose down && docker-compose build --no-cache frontend backend && docker-compose up -d && docker-compose ps'
+```
+
+This matches the workflow: **local code → Git → rsync to server → Docker rebuild**.