first commit

q1-deploy-monitor/README.md

@@ -0,0 +1,97 @@
+# نشر تطبيق ومراقبته على غيمة (Ghaymah Containers)
+
+حل كامل لنشر واجهة برمجية (API) بسيطة على منصة الحاويات في `ghaymah.systems`، مع سكربت مراقبة ولوحة تحكم مباشرة.
+
+## محتويات المشروع
+```
+.
+├── Dockerfile
+├── requirements.txt
+├── .dockerignore
+├── app/
+│   └── main.py            # تطبيق Flask + /health + /metrics
+├── health-check.sh        # سكربت مراقبة بلغة bash (فحص كل 30 ثانية)
+├── health-check.py
+└── dashboard.html         # لوحة مراقبة (HTML/CSS/JS) تعمل من المتصفح مباشرة
+```
+
+## 1) بناء واختبار الصورة محليًا
+```bash
+docker build -t sample-api:latest .
+docker run --rm -p 8080:8080 sample-api:latest
+
+# في نافذة أخرى
+curl http://localhost:8080/health
+curl http://localhost:8080/metrics
+```
+
+## 2) النشر على ghaymah.systems
+
+منصة الحاويات في Ghaymah تدعم النشر إما عبر ربط مستودع Git (بناء تلقائي من الـ Dockerfile) أو عبر دفع صورة جاهزة إلى سجل الحاويات الخاص بها. الخطوات العامة:
+
+1. سجّل الدخول إلى console الخاص بـ **ghaymah.systems**.
+2. من قسم **Containers**، اختر **New Service / Deploy Container**.
+3. اختر مصدر النشر:
+   - **Git Repository**: اربط المستودع الذي يحتوي هذا المشروع (يجب أن يحتوي على `Dockerfile` في الجذر) — المنصة تبني الصورة تلقائيًا من الـ Dockerfile.
+   - **أو Container Registry**: ابنِ وادفع الصورة يدويًا:
+     ```bash
+     docker build -t <registry>/<namespace>/sample-api:1.0 .
+     docker push <registry>/<namespace>/sample-api:1.0
+     ```
+     ثم أدخل مسار الصورة هذا عند إنشاء الخدمة.
+4. اضبط إعدادات الخدمة:
+   - **Port**: `8080` (نفس المنفذ في `EXPOSE` وفي `PORT` env).
+   - **Health Check Path**: `/health` (المنصة تستخدمه لمعرفة جاهزية الحاوية).
+   - **Environment Variables**: أضف `PORT=8080` إن احتاج الأمر.
+   - **Resources**: ابدأ بأصغر خطة (0.5 vCPU / 256-512MB) كافية لهذا التطبيق التجريبي.
+5. اضغط **Deploy**. بعد اكتمال النشر ستحصل على رابط عام مثل:
+   `https://sample-api-xxxx.ghaymah.systems`
+6. تحقق من النشر:
+   ```bash
+   curl https://sample-api-xxxx.ghaymah.systems/health
+   ```
+
+> ملاحظة: أسماء الأزرار والحقول الدقيقة قد تختلف قليلًا حسب نسخة الواجهة الحالية على `ghaymah.systems` — الخطوات أعلاه تعكس تدفق العمل القياسي لمنصات الحاويات (Container-as-a-Service)، راجع `docs.ghaymah.cloud` لأي تفاصيل محدّثة.
+
+## 3) تشغيل سكربت المراقبة
+
+بعد النشر، شغّل سكربت المراقبة موجّهًا إلى الرابط العام للتطبيق:
+
+```bash
+# Python (الخيار الموصى به)
+python health-check.py --url https://sample-api-xxxx.ghaymah.systems --interval 30
+
+# أو bash
+chmod +x monitor.sh
+./monitor.sh https://sample-api-xxxx.ghaymah.systems 30
+```
+
+السكربت يقوم بـ:
+- فحص `/health` كل 30 ثانية.
+- تسجيل الحالة وزمن الاستجابة في `monitor.log`.
+- كتابة آخر نتيجة في `status.json`.
+- إطلاق تنبيه (`ALERT`) في السجل بعد 3 فحوصات فاشلة متتالية.
+
+يمكن تشغيله كخدمة نظام دائمة (systemd) أو كحاوية منفصلة (sidecar) بجانب التطبيق نفسه.
+
+## 4) لوحة المراقبة (Dashboard)
+
+افتح `dashboard.html` مباشرة في المتصفح (لا يحتاج خادمًا، ملف ثابت واحد):
+
+1. أدخل الرابط العام للتطبيق في حقل الاتصال، مثل:
+   `https://sample-api-xxxx.ghaymah.systems`
+2. اضغط **اتصال**.
+
+تعرض اللوحة:
+- **الحالة**: مؤشر أخضر (يعمل) / أحمر (متوقف)، مع نبض حي عند التشغيل السليم.
+- **زمن الاستجابة**: آخر قيمة + رسم بياني لآخر 30 قراءة.
+- **عدد الطلبات**: القيمة الإجمالية القادمة من `/metrics`.
+- **مدة التشغيل** وسجل مباشر لكل عملية فحص.
+
+اللوحة تستدعي `/metrics` كل 5 ثوانٍ عبر `fetch()` مباشرة من المتصفح؛ التطبيق (`main.py`) يضيف ترويسة `Access-Control-Allow-Origin: *` لذلك لا حاجة لخادم وسيط.
+
+## ملاحظات إنتاجية (Production Notes)
+- التطبيق يعمل بمستخدم غير جذري (`non-root user`) داخل الحاوية.
+- يُستخدم `gunicorn` كخادم WSGI إنتاجي بدلاً من خادم التطوير المدمج في Flask.
+- `HEALTHCHECK` مضمّن في الـ Dockerfile نفسه، بالإضافة إلى فحص خارجي (`health-check.py`) — طبقتا مراقبة مستقلتان.
+- للتوسع: يمكن رفع عدد النسخ (replicas) من إعدادات الخدمة في Ghaymah دون تعديل الكود.