docs: add staging Docker deploy guide for remote developers

Made-with: Cursor

DEVELOPER_STAGING_DEPLOY.md

@@ -0,0 +1,164 @@
+# Staging deploy guide (for developers)
+
+This document explains how to get **code you pushed to Git** onto the **staging server** and running inside **Docker**. Pushing to the remote repository updates Git only; the live staging app updates only after you **sync files to the server** and **rebuild/restart the containers** (or after automated CI/CD, if you add it later).
+
+**Staging URL (public site):** https://zerp.atmata-group.com/
+
+---
+
+## 1. What you need first
+
+Ask your team lead for:
+
+| Item | Why |
+|------|-----|
+| **SSH access** to the staging server (host, user, key or password) | You run deploy commands on the server |
+| **Project path on the server** | This repo uses `/root/z_crm` (confirm if your environment differs) |
+| **Whether Git is installed on the server** inside that folder | Decides whether you use **Git pull** or **rsync** (see below) |
+
+You do **not** need Node.js on the server for a normal deploy: Docker builds the frontend and backend **inside** the images.
+
+---
+
+## 2. Before you push (recommended)
+
+On your laptop, from the project root:
+
+```bash
+cd frontend && npm run build
+cd ../backend && npm run build
+```
+
+If either command fails, fix the errors before pushing. This catches broken TypeScript or Next.js issues early.
+
+---
+
+## 3. After your commit is on the remote (Git server)
+
+Make sure your branch is merged or pushed to the branch the team deploys from (usually `master`).
+
+---
+
+## 4. Deploy path A — Server has a Git clone (preferred)
+
+If `/root/z_crm` is a **Git repository** (`ls -la /root/z_crm/.git` exists) and the server can reach your Git remote:
+
+### Step 1 — SSH into the server
+
+```bash
+ssh root@YOUR_SERVER_IP
+```
+
+(Replace user/host with what you were given.)
+
+### Step 2 — Go to the project directory
+
+```bash
+cd /root/z_crm
+```
+
+### Step 3 — Pull the latest code
+
+```bash
+git fetch origin
+git pull origin master
+```
+
+If your team uses another branch for staging, replace `master` with that branch name.
+
+### Step 4 — Stop containers, rebuild app images, start again
+
+Rebuilding **frontend** and **backend** is enough for most code changes (Postgres data is kept on its Docker volume):
+
+```bash
+docker-compose down
+docker-compose build --no-cache frontend backend
+docker-compose up -d
+```
+
+### Step 5 — Check that everything is up
+
+```bash
+docker-compose ps
+```
+
+You want `zerp_postgres`, `zerp_backend`, and `zerp_frontend` running. Postgres should show as **healthy**.
+
+### Step 6 — If something fails
+
+```bash
+docker-compose logs backend --tail 80
+docker-compose logs frontend --tail 80
+```
+
+---
+
+## 5. Deploy path B — Server has **no** Git (files only)
+
+Some setups copy the project with **rsync** and **exclude** `.git`, so there is nothing to `git pull` on the server.
+
+Then one of these must happen **before** the Docker steps:
+
+- Someone with access **rsyncs** the repo from a machine that has the latest `git pull`, **or**
+- You set up a **fresh `git clone`** once on the server (with a deploy key or token) and switch to **path A** for future deploys.
+
+After the files on disk under `/root/z_crm` match what you want, run the same Docker commands as in **path A, step 4–6**:
+
+```bash
+cd /root/z_crm
+docker-compose down
+docker-compose build --no-cache frontend backend
+docker-compose up -d
+docker-compose ps
+```
+
+---
+
+## 6. Important: `.env` on the server
+
+The backend needs a **`DATABASE_URL`** (and related variables) on the server. These usually live in a file **`/root/z_crm/.env`** that is **not** committed to Git.
+
+- **Do not** delete or overwrite that file when copying the project.
+- If you use **rsync** from your laptop, exclude `.env` so the server keeps its real secrets (your lead can give you the exact `rsync` flags).
+
+If the backend container exits immediately with Prisma or database errors, ask your lead to verify `.env` on the server.
+
+---
+
+## 7. Database migrations
+
+The backend container is configured to run **`npx prisma migrate deploy`** on startup. After you deploy schema changes, a normal **`docker-compose up -d`** (after rebuild) applies pending migrations when the backend starts.
+
+---
+
+## 8. Quick reference (copy-paste)
+
+**Git on server:**
+
+```bash
+ssh root@YOUR_SERVER_IP
+cd /root/z_crm
+git pull origin master
+docker-compose down
+docker-compose build --no-cache frontend backend
+docker-compose up -d
+docker-compose ps
+```
+
+---
+
+## 9. Optional: rebuild everything (slower)
+
+If you changed **docker-compose.yml** or want a completely clean image build for all services:
+
+```bash
+docker-compose down
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+This still keeps the Postgres **volume** (your data) unless someone removes volumes on purpose.
+
+---
+
+If your team later adds **CI/CD** (e.g. GitLab/GitHub Action that SSHs in and runs these commands after each push to `master`), you can replace most of this manual process with an automated pipeline.