zerp/DEVELOPER_STAGING_DEPLOY.md

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:

   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

git pull origin master

Resolve any conflicts, then make sure your changes are committed and pushed:

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:

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:

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

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

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:

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:

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:

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)

# 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.