From 58a6bcba7333387c1ec54680c043ce3e96e24c06 Mon Sep 17 00:00:00 2001 From: CyberMind-FR Date: Fri, 26 Dec 2025 20:40:28 +0100 Subject: [PATCH] docs: add critical pre-deployment checks and common error solutions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive pre-deployment verification to prevent common issues: 🔍 Pre-Deployment Checks (CRITICAL) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. Disk Space Verification - Check overlay usage before deployment - Stop if ≄90% full - Emergency cleanup procedures 2. Permissions Verification (Prevent HTTP 403) - RPCD: 755 (rwxr-xr-x) - CSS/JS: 644 (rw-r--r--) - Common error: Files created with 600 instead of 644 - Symptom: HTTP 403 Forbidden on resource loading 3. Post-Deployment Verification - 6-point checklist script - Verify disk space, permissions, ubus objects - Automated validation 4. Common Deployment Errors Table - HTTP 403 Forbidden → Permission fix - No space left → Cleanup procedure - Object not found → RPCD permission check - Module not appearing → Cache clearing - Changes not visible → Browser cache 5. Emergency Disk Space Recovery - Analysis commands - Cleanup procedures - Netdata web UI removal option (saves 22MB) 📝 Files Updated: - DEVELOPMENT-GUIDELINES.md: Added ~175 lines at section 9 - QUICK-START.md: Added rules #4 and #5 Based on real deployment issues encountered: - Router overlay 100% full (98.8M/98.8M) - HTTP 403 on netdata-dashboard (permissions 600 vs 644) - Common.css deployment failures due to space These checks are now MANDATORY before any deployment. đŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- DEVELOPMENT-GUIDELINES.md | 176 ++++++++++++++++++++++++++++++++++++++ QUICK-START.md | 30 +++++++ 2 files changed, 206 insertions(+) diff --git a/DEVELOPMENT-GUIDELINES.md b/DEVELOPMENT-GUIDELINES.md index c44dec8d..668b0a16 100644 --- a/DEVELOPMENT-GUIDELINES.md +++ b/DEVELOPMENT-GUIDELINES.md @@ -1201,6 +1201,182 @@ AprĂšs dĂ©ploiement: ## Deployment Procedures +### ⚠ Pre-Deployment Checks (CRITICAL) + +**TOUJOURS exĂ©cuter ces vĂ©rifications AVANT tout dĂ©ploiement:** + +#### 1. VĂ©rification de l'Espace Disque + +```bash +# Sur le routeur cible +ssh root@192.168.8.191 "df -h | grep overlay" + +# VĂ©rifier que l'utilisation est < 90% +# Exemple OK: +# /dev/loop0 98.8M 45.2M 53.6M 46% /overlay + +# Exemple CRITIQUE (STOP deployment): +# /dev/loop0 98.8M 98.8M 0 100% /overlay ← PLEIN! +``` + +**Si l'overlay est plein (≄95%):** +```bash +# LibĂ©rer de l'espace avant dĂ©ploiement +ssh root@192.168.8.191 << 'EOF' +# Supprimer fichiers temporaires +rm -rf /tmp/*.ipk /tmp/luci-* 2>/dev/null + +# Supprimer anciens backups (>7 jours) +find /root -name '*.backup-*' -type f -mtime +7 -delete 2>/dev/null + +# VĂ©rifier packages inutilisĂ©s +opkg list-installed | grep -E 'netdata|unused' + +# AprĂšs nettoyage, vĂ©rifier l'espace libĂ©rĂ© +df -h | grep overlay +EOF +``` + +**Tailles typiques Ă  surveiller:** +- Netdata web UI: ~22MB (considĂ©rer suppression si non utilisĂ©) +- Modules LuCI: ~1-2MB chacun +- Fichiers CSS/JS: ~10-50KB chacun + +#### 2. VĂ©rification des Permissions (Critique pour Éviter Erreurs 403) + +**Permissions OBLIGATOIRES:** + +| Type | Permission | Octal | Raison | +|------|-----------|-------|--------| +| **RPCD scripts** | `rwxr-xr-x` | `755` | ExĂ©cutable par system | +| **CSS files** | `rw-r--r--` | `644` | Lecture web server | +| **JS files** | `rw-r--r--` | `644` | Lecture web server | +| **JSON files** | `rw-r--r--` | `644` | Lecture rpcd | + +**Erreur commune:** Fichiers crĂ©Ă©s avec `600` (rw-------) au lieu de `644` + +**SymptĂŽme:** HTTP 403 Forbidden lors du chargement de fichiers JS/CSS + +**Exemple d'erreur:** +``` +NetworkError: HTTP error 403 while loading class file +"/luci-static/resources/view/netdata-dashboard/dashboard.js" +``` + +**Diagnostic rapide:** +```bash +# VĂ©rifier permissions des fichiers dĂ©ployĂ©s +ssh root@192.168.8.191 "ls -la /www/luci-static/resources/view/MODULE_NAME/" + +# Chercher fichiers avec permissions incorrectes (600) +ssh root@192.168.8.191 "find /www/luci-static/resources/view/ -type f -name '*.js' -perm 600" + +# MAUVAIS (cause 403): +# -rw------- 1 root root 9763 dashboard.js ← 600 = pas lisible par web! + +# BON: +# -rw-r--r-- 1 root root 9763 dashboard.js ← 644 = OK +``` + +**Correction immĂ©diate:** +```bash +# Corriger TOUS les fichiers CSS/JS +ssh root@192.168.8.191 << 'EOF' +find /www/luci-static/resources/ -name '*.css' -exec chmod 644 {} \; +find /www/luci-static/resources/ -name '*.js' -exec chmod 644 {} \; +find /usr/libexec/rpcd/ -name 'luci.*' -exec chmod 755 {} \; +EOF +``` + +#### 3. Post-Deployment Verification + +**Checklist aprĂšs dĂ©ploiement:** + +```bash +#!/bin/bash +ROUTER="root@192.168.8.191" +MODULE="module-name" + +echo "🔍 Post-Deployment Verification" +echo "" + +# 1. VĂ©rifier espace disque +echo "1. Espace disque restant:" +ssh "$ROUTER" "df -h | grep overlay | awk '{print \$5}'" || echo "❌ FAIL" + +# 2. VĂ©rifier permissions CSS/JS +echo "2. Permissions CSS/JS:" +ssh "$ROUTER" "find /www/luci-static/resources/$MODULE -type f \( -name '*.css' -o -name '*.js' \) ! -perm 644" | \ + if [ -z "$(cat)" ]; then echo "✅ OK"; else echo "❌ FAIL - Permissions incorrectes"; fi + +# 3. VĂ©rifier permissions RPCD +echo "3. Permissions RPCD:" +ssh "$ROUTER" "ls -l /usr/libexec/rpcd/luci.$MODULE | grep -q rwxr-xr-x" && echo "✅ OK" || echo "❌ FAIL" + +# 4. VĂ©rifier ubus object +echo "4. ubus object disponible:" +ssh "$ROUTER" "ubus list | grep -q luci.$MODULE" && echo "✅ OK" || echo "❌ FAIL" + +# 5. VĂ©rifier fichiers accessibles (HTTP) +echo "5. Fichiers web accessibles:" +ssh "$ROUTER" "test -r /www/luci-static/resources/$MODULE/common.css" && echo "✅ OK" || echo "⚠ common.css non trouvĂ©" + +# 6. VĂ©rifier cache cleared +echo "6. Cache LuCI cleared:" +ssh "$ROUTER" "test ! -f /tmp/luci-indexcache" && echo "✅ OK" || echo "⚠ Cache encore prĂ©sent" + +echo "" +echo "✅ VĂ©rification terminĂ©e" +``` + +#### 4. Common Deployment Errors + +| Erreur | Cause | Solution Rapide | +|--------|-------|----------------| +| **HTTP 403 Forbidden** | Permissions 600 au lieu de 644 | `chmod 644 *.js *.css` | +| **No space left on device** | Overlay plein | Nettoyer /tmp, supprimer anciens backups | +| **Object not found -32000** | RPCD pas exĂ©cutable ou mal nommĂ© | `chmod 755 rpcd/luci.*` + vĂ©rifier nom | +| **Module not appearing** | Cache LuCI pas cleared | `rm /tmp/luci-*` + restart services | +| **Changes not visible** | Cache navigateur | Mode privĂ© + Ctrl+Shift+R | + +#### 5. Emergency Disk Space Recovery + +**Si le dĂ©ploiement Ă©choue avec "No space left on device":** + +```bash +#!/bin/bash +ROUTER="root@192.168.8.191" + +echo "🚹 Emergency Disk Space Recovery" +echo "" + +# 1. Analyser l'utilisation +echo "Top 10 consumers:" +ssh "$ROUTER" "du -k /overlay/upper 2>/dev/null | sort -rn | head -10" + +# 2. Nettoyer temporaires +echo "" +echo "Cleaning temp files..." +ssh "$ROUTER" "rm -rf /tmp/*.ipk /tmp/luci-* /root/*.ipk 2>/dev/null" + +# 3. Supprimer anciens backups +echo "Removing old backups (>7 days)..." +ssh "$ROUTER" "find /root -name '*.backup-*' -mtime +7 -delete 2>/dev/null" + +# 4. Option: Supprimer Netdata Web UI (libĂšre ~22MB) +echo "" +echo "⚠ Option: Remove Netdata Web UI (saves ~22MB)?" +read -p "Continue? (y/N) " -n 1 -r +if [[ $REPLY =~ ^[Yy]$ ]]; then + ssh "$ROUTER" "opkg remove netdata-web 2>/dev/null || rm -rf /usr/share/netdata/web/*" +fi + +# 5. VĂ©rifier espace libĂ©rĂ© +echo "" +echo "Space after cleanup:" +ssh "$ROUTER" "df -h | grep overlay" +``` + ### Standard Deployment Script Template ```bash diff --git a/QUICK-START.md b/QUICK-START.md index 0e28e239..e348a549 100644 --- a/QUICK-START.md +++ b/QUICK-START.md @@ -36,6 +36,36 @@ chmod 644 htdocs/**/*.{css,js} # Sinon: 403 Forbidden ou script non exĂ©cutĂ© ``` +### 4. Pre-Deployment Checks +```bash +# TOUJOURS vĂ©rifier avant dĂ©ploiement: + +# 1. Espace disque (doit ĂȘtre < 90%) +ssh root@192.168.8.191 "df -h | grep overlay" + +# 2. Permissions aprĂšs dĂ©ploiement +ssh root@192.168.8.191 "find /www/luci-static -name '*.js' -perm 600" +# ⚠ Si rĂ©sultats: fichiers ont 600 au lieu de 644 → Erreur 403! + +# 3. Correction rapide si nĂ©cessaire +ssh root@192.168.8.191 "find /www/luci-static -name '*.css' -exec chmod 644 {} \;" +ssh root@192.168.8.191 "find /www/luci-static -name '*.js' -exec chmod 644 {} \;" +``` + +### 5. Common Errors Quick Fix +```bash +# HTTP 403 Forbidden +chmod 644 /www/luci-static/resources/**/*.{js,css} + +# No space left on device +rm -rf /tmp/*.ipk /tmp/luci-* +find /root -name '*.backup-*' -mtime +7 -delete + +# Object not found -32000 +chmod 755 /usr/libexec/rpcd/luci.* +ubus list | grep luci.module-name # VĂ©rifier disponibilitĂ© +``` + --- ## 🎹 Design System Essentials