Skip to content

Commit 23e7720

Browse files
rajashish147rajashish147
committed
docs(rollback): add comprehensive rollback system documentation
- Add ROLLBACK_QUICKREF.md with quick reference commands and workflows - Add ROLLBACK_SYSTEM.md with detailed architecture and implementation guide - Include deployment and rollback flow diagrams for visual reference - Document safety features, troubleshooting, and performance metrics - Provide example sessions and common usage patterns - Enable operators to quickly understand and execute rollback procedures
1 parent 35db851 commit 23e7720

2 files changed

Lines changed: 442 additions & 0 deletions

File tree

‎backend/docs/ROLLBACK_QUICKREF.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Rollback System Quick Reference
2+
3+
## Commands
4+
5+
### Deploy Latest Version
6+
```bash
7+
cd /home/ashish/FieldTrack-2.0/backend
8+
./scripts/deploy-bluegreen.sh <SHA>
9+
```
10+
11+
### Rollback to Previous Version
12+
```bash
13+
cd /home/ashish/FieldTrack-2.0/backend
14+
./scripts/rollback.sh
15+
```
16+
17+
### Deploy Specific Version
18+
```bash
19+
./scripts/deploy-bluegreen.sh 7b3e9f1
20+
```
21+
22+
## How It Works
23+
24+
1. Every successful deployment prepends image SHA to `.deploy_history`
25+
2. History maintains last 5 deployments (newest first)
26+
3. Rollback reads line 2 from `.deploy_history` and redeploys that image
27+
4. Blue-green deployment ensures zero downtime
28+
5. Health checks validate before switching traffic
29+
30+
## Deployment Flow
31+
32+
```
33+
┌──────────────┐
34+
│ CI builds │
35+
│ image SHA │
36+
└──────┬───────┘
37+
│
38+
▼
39+
┌──────────────────┐
40+
│ deploy-blue │
41+
│ green.sh <SHA> │
42+
└──────┬───────────┘
43+
│
44+
▼
45+
┌──────────────────┐
46+
│ Pull image │
47+
│ Start container │
48+
│ Health check │
49+
│ Switch nginx │
50+
└──────┬───────────┘
51+
│
52+
▼
53+
┌──────────────────┐
54+
│ Prepend SHA to │
55+
│ .deploy_history │
56+
│ (keep last 5) │
57+
└──────────────────┘
58+
```
59+
60+
## Rollback Flow
61+
62+
```
63+
┌──────────────────┐
64+
│ ./rollback.sh │
65+
└──────┬───────────┘
66+
│
67+
▼
68+
┌──────────────────┐
69+
│ Read .deploy_ │
70+
│ history (line 2) │
71+
└──────┬───────────┘
72+
│
73+
▼
74+
┌──────────────────┐
75+
│ Show history & │
76+
│ confirm with user│
77+
└──────┬───────────┘
78+
│
79+
▼
80+
┌──────────────────┐
81+
│ deploy-blue │
82+
│ green.sh <SHA> │
83+
└──────────────────┘
84+
```
85+
86+
## Safety Features
87+
88+
- ✅ Interactive confirmation before rollback
89+
- ✅ Health check validation (20 attempts × 3s)
90+
- ✅ Nginx config validation before reload
91+
- ✅ Automatic cleanup on failure
92+
- ✅ Zero downtime blue-green deployment
93+
- ✅ Immutable image SHAs
94+
95+
## File Locations
96+
97+
```
98+
/home/ashish/FieldTrack-2.0/backend/
99+
├── scripts/
100+
│ ├── deploy-bluegreen.sh
101+
│ └── rollback.sh
102+
└── .deploy_history (last 5 SHAs)
103+
```
104+
105+
## Example Session
106+
107+
```bash
108+
# Deploy new version
109+
$ ./scripts/deploy-bluegreen.sh b8c4d2e
110+
[1/7] Pulling image...
111+
[2/7] Detecting active container...
112+
[3/7] Starting inactive container...
113+
[4/7] Waiting for health check...
114+
[5/7] Switching nginx upstream...
115+
[6/7] Reloading nginx...
116+
[7/7] Cleaning old container...
117+
Deployment successful.
118+
Deployment history updated: b8c4d2e
119+
120+
# Issue discovered - rollback
121+
$ ./scripts/rollback.sh
122+
Current deployment : b8c4d2e
123+
Previous deployment: a4f91c2
124+
125+
Deployment history:
126+
1. b8c4d2e (current)
127+
2. a4f91c2 ← rollback target
128+
3. 7b3e9f1
129+
130+
⚠️ WARNING: This will redeploy the previous version.
131+
Current production will be replaced with: a4f91c2
132+
133+
Continue with rollback? (yes/no): yes
134+
135+
Starting rollback to image: a4f91c2
136+
[1/7] Pulling image...
137+
...
138+
Rollback completed successfully.
139+
Production is now running: a4f91c2
140+
```
141+
142+
## Troubleshooting
143+
144+
| Issue | Solution |
145+
|-------|----------|
146+
| Script not executable | `chmod +x backend/scripts/rollback.sh` |
147+
| No deployment history | Deploy at least once before rollback |
148+
| Insufficient history | Need at least 2 deployments to rollback |
149+
| Image not found | Verify SHA exists in GHCR |
150+
| Health check fails | Check logs: `docker logs backend-blue` |
151+
152+
## Performance
153+
154+
- **Rollback time:** <10 seconds
155+
- **Health check:** Up to 60 seconds
156+
- **Zero downtime:** Always maintained
157+
158+
## Related Docs
159+
160+
- [Full Documentation](./ROLLBACK_SYSTEM.md)
161+
- [Deployment Guide](./DEPLOYMENT.md)

0 commit comments

Comments
 (0)