From 1014d8831334e036eae819c94ee974d6a387362c Mon Sep 17 00:00:00 2001 From: Talal Sharabi Date: Wed, 1 Apr 2026 11:23:32 +0400 Subject: [PATCH] docs: add staging Docker deploy guide for remote developers Made-with: Cursor --- DEVELOPER_STAGING_DEPLOY.md | 164 ++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 DEVELOPER_STAGING_DEPLOY.md diff --git a/DEVELOPER_STAGING_DEPLOY.md b/DEVELOPER_STAGING_DEPLOY.md new file mode 100644 index 0000000..d4c5ddd --- /dev/null +++ b/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.