docs: align developer staging guide with rsync + Docker workflow
Made-with: Cursor
This commit is contained in:
Talal Sharabi
@@ -1,110 +1,92 @@
|
||||
# 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).
|
||||
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 (public site):** https://zerp.atmata-group.com/
|
||||
**Staging URL:** https://zerp.atmata-group.com/
|
||||
|
||||
**Server project path:** `/root/z_crm` (confirm with your lead if different)
|
||||
|
||||
---
|
||||
|
||||
## 1. What you need first
|
||||
## 1. What you need from your lead
|
||||
|
||||
Ask your team lead for:
|
||||
| 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 |
|
||||
|
||||
| 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.
|
||||
You do **not** need Node.js **on the server**. Docker runs `npm ci` and `npm run build` inside the containers.
|
||||
|
||||
---
|
||||
|
||||
## 2. Before you push (recommended)
|
||||
## 2. One-time setup on your laptop
|
||||
|
||||
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.
|
||||
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. After your commit is on the remote (Git server)
|
||||
## 3. Standard deploy (every time you want staging updated)
|
||||
|
||||
Make sure your branch is merged or pushed to the branch the team deploys from (usually `master`).
|
||||
Run these from your **project root** (the folder that contains `frontend/`, `backend/`, and `docker-compose.yml`).
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
### Step 1 — Get the code you want on Git
|
||||
|
||||
```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):
|
||||
Resolve any conflicts, then make sure your changes are **committed and pushed**:
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
docker-compose build --no-cache frontend backend
|
||||
docker-compose up -d
|
||||
git push origin master
|
||||
```
|
||||
|
||||
### Step 5 — Check that everything is up
|
||||
(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
|
||||
docker-compose ps
|
||||
cd frontend && npm run build && cd ../backend && npm run build && cd ..
|
||||
```
|
||||
|
||||
You want `zerp_postgres`, `zerp_backend`, and `zerp_frontend` running. Postgres should show as **healthy**.
|
||||
If either build fails, fix the problem and repeat before continuing.
|
||||
|
||||
### Step 6 — If something fails
|
||||
### Step 3 — Sync files to the server (rsync)
|
||||
|
||||
From the **project root**:
|
||||
|
||||
```bash
|
||||
docker-compose logs backend --tail 80
|
||||
docker-compose logs frontend --tail 80
|
||||
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`.
|
||||
|
||||
## 5. Deploy path B — Server has **no** Git (files only)
|
||||
Replace `YOUR_USER` and `YOUR_SERVER_HOST` with what your lead gave you.
|
||||
|
||||
Some setups copy the project with **rsync** and **exclude** `.git`, so there is nothing to `git pull` on the server.
|
||||
### Step 4 — Rebuild Docker on the server
|
||||
|
||||
Then one of these must happen **before** the Docker steps:
|
||||
Either open an SSH session and run the commands, or run them in one shot:
|
||||
|
||||
- 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**:
|
||||
**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
|
||||
@@ -112,53 +94,81 @@ 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:**
|
||||
**Option B — One line from your laptop**
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_SERVER_IP
|
||||
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
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
If there is **no** `.git` on the server (typical when deploys have always been rsync), use **section 3** only.
|
||||
|
||||
---
|
||||
|
||||
## 9. Optional: rebuild everything (slower)
|
||||
|
||||
If you changed **docker-compose.yml** or want a completely clean image build for all services:
|
||||
## 8. Copy-paste cheat sheet (replace user/host)
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
# 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 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.
|
||||
This matches the workflow: **local code → Git → rsync to server → Docker rebuild**.
|
||||
|
||||
Reference in New Issue
Block a user