Add setup.md

setup.md

@@ -0,0 +1,327 @@
+
+ # بسم الله الرحمن الرحيم
+
+إليك الدليل الكامل لاستخدام `cumin-sdk`، والذي يتيح التحكم البرمجي في موارد الحوسبة السحابية عبر بايثون، مُنسق بأسلوب توثيقي احترافي:
+
+---
+
+# 📘 دليل استخدام Cumin SDK
+
+**Cumin SDK** هي مكتبة بايثون الرسمية لمنصة **غيمة** (Ghaymah Systems)، تمكنك من التحكم الكامل في الموارد السحابية برمجياً. تتيح لك إنشاء وإدارة المشاريع، التطبيقات، قواعد البيانات، التخزين، والكثير من الخدمات السحابية بأسلوب برمجي سهل ومرن (يدعم التزامن Sync وعدم التزامن Async).
+
+---
+
+## 📦 التثبيت (Installation)
+
+للبدء، قم بتثبيت الحزمة من سجل غيمة. تأكد من استخدام الرابط الصحيح للسجل الخاص بنا:
+
+```bash
+pip install cumin-sdk --index-url https://pypi.ghaymah.systems/simple
+```
+
+> **ملاحظة:** إذا كنت تستخدم ملف `pip.conf` كما شرحنا سابقاً، يمكنك الاكتفاء بالأمر `pip install cumin-sdk` فقط.
+
+---
+
+## 🚀 البدء السريع (Initialization)
+
+للاستخدام الأساسي، تحتاج إلى توكن API الخاص بك للتوثيق.
+
+### الاستخدام المتزامن (Synchronous)
+
+إليك مثال سريع لإنشاء مشروع وتطبيق:
+
+```python
+from cumin import CuminClient
+
+# تهيئة العميل باستخدام توكن الـ API
+client = CuminClient(token="your-api-token")
+
+# إنشاء مشروع جديد
+project = client.create_project({"name": "my-project"})
+print(f"تم إنشاء المشروع: {project['id']}")
+
+# بيانات التطبيق
+app_data = {
+    "name": "my-app",
+    "instances": 1,
+    "hibernated": False,
+    "image": "nginx:latest",
+    "ports": [{"name": "web", "number": 80}],
+    "env": [{"name": "NODE_ENV", "value": "production"}],
+    "mounts": []
+}
+
+# إنشاء التطبيق
+app = client.create_app(app_data)
+print(f"تم إنشاء التطبيق: {app['id']}")
+
+# عرض قائمة جميع التطبيقات
+apps = client.list_apps()
+for app in apps:
+    print(f"التطبيق: {app['name']} (ID: {app['id']})")
+```
+
+### الاستخدام غير المتزامن (Asynchronous)
+
+للأداء العالي والتطبيقات التي تتطلب معالجة متوازية، يدعم الـ SDK `async/await`:
+
+```python
+import asyncio
+from cumin import CuminClient
+
+async def main():
+    # استخدام مدير السياق (Context Manager) للإدارة التلقائية للجلسات
+    async with CuminClient(token="your-api-token") as client:
+        # إنشاء مشروع بشكل غير متزامن
+        project = await client.create_project_async({"name": "my-project"})
+        print(f"تم إنشاء المشروع: {project['id']}")
+        
+        # عرض التطبيقات بشكل غير متزامن
+        apps = await client.list_apps_async()
+        for app in apps:
+            print(f"التطبيق: {app['name']} (ID: {app['id']})")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 📚 مرجع الـ API (API Reference)
+
+### تهيئة العميل (Client Initialization)
+
+يمكنك تخصيص العميل لاستخدام رابط API مختلف أو لبيئات أخرى:
+
+```python
+from cumin import CuminClient
+
+# التهيئة الأساسية
+client = CuminClient(token="your-api-token")
+
+# تحديد رابط API مخصص
+client = CuminClient(
+    token="your-api-token",
+    base_url="https://api.cumin.dev"
+)
+
+# استخدام غير متزامن مع مدير السياق
+async with CuminClient(token="your-api-token") as client:
+    await client.health_async()
+```
+
+---
+
+### 🗂️ إدارة المشاريع (Project Management)
+
+إنشاء وتحديث المشاريع الخاصة بك:
+
+```python
+# إنشاء مشروع
+project = client.create_project({"name": "project-name"})
+
+# تحديث بيانات المشروع
+updated = client.update_project({
+    "id": "project-id",
+    "name": "new-name"
+})
+```
+
+---
+
+### 📱 إدارة التطبيقات (App Management)
+
+التحكم الكامل في دورة حياة التطبيقات (الحاويات/Containers):
+
+```python
+# إنشاء تطبيق جديد
+app = client.create_app({
+    "name": "my-app",
+    "instances": 1,
+    "hibernated": False,
+    "image": "nginx:latest",
+    "ports": [{"name": "web", "number": 80}],
+    "env": [{"name": "ENV_VAR", "value": "value"}],
+    "mounts": []
+})
+
+# تحديث تطبيق (مثلاً زيادة النسخ)
+updated_app = client.update_app({
+    "id": "app-id",
+    "name": "updated-name",
+    "instances": 2,
+    "hibernated": False,
+    "image": "nginx:latest",
+    "ports": [{"name": "web", "number": 80}],
+    "env": [],
+    "mounts": []
+})
+
+# حذف تطبيق
+client.delete_app("app-id")
+
+# عرض جميع التطبيقات
+apps = client.list_apps()
+```
+
+---
+
+### 💾 إدارة وحدات التخزين (Volume Management)
+
+إنشاء وإدارة الأقراص الصلبة الافتراضية:
+
+```python
+# إنشاء حجم تخزين (الحجم بالبايت)
+volume = client.create_volume({
+    "name": "my-volume",
+    "size": 1073741824  # تساوي 1 جيجابايت
+})
+
+# عرض وحدات التخزين
+volumes = client.list_volumes()
+```
+
+---
+
+### 🔐 إدارة مفاتيح السحب (Pull Secrets)
+
+إدارة بيانات الاعتماد لسحب الصور من مسجلات Docker الخاصة:
+
+```python
+# إنشاء Pull Secret للوصول إلى Docker Hub مثلاً
+secret = client.create_pull_secret({
+    "name": "docker-hub",
+    "username": "myuser",
+    "password": "mypassword",
+    "server": "https://index.docker.io/v1/"
+})
+
+# عرض الـ Secrets المحفوظة
+secrets = client.list_pull_secrets()
+```
+
+---
+
+### 🪣 إدارة التخزين S3
+
+إنشاء وإدارة خدمات التخزين Object Storage:
+
+```python
+# إنشاء نسخة S3
+s3 = client.create_s3({
+    "hibernated": False,
+    "tags": {"environment": "production"}
+})
+
+# جلب إعدادات S3 الحالية
+s3_config = client.get_s3()
+```
+
+---
+
+### 🗝️ إدارة الأسرار (Secrets Management)
+
+إدارة متغيرات البيئة الحساسة للمشاريع:
+
+```python
+# إنشاء سر (Secret)
+client.create_secret({
+    "key": "API_KEY",
+    "project_id": "project-id",
+    "value": "secret-value"
+})
+
+# عرض الأسرار
+secrets = client.list_secrets()
+```
+
+---
+
+### 🐘 إدارة قواعد بيانات Postgres
+
+إنشاء وإدارة قواعد بيانات PostgreSQL المدارة:
+
+```python
+# إنشاء قاعدة بيانات Postgres جديدة
+pg = client.create_postgres({
+    "name": "my-database",
+    "hibernated": False,
+    "volume_id": "volume-id",  # يجب ربطها بوحدة تخزين
+    "postgres_version": "15",
+    "postgres_db": "mydb",
+    "postgres_user": "admin",
+    "postgres_password": "securepassword"
+})
+
+# عرض قواعد البيانات
+databases = client.list_postgres()
+```
+
+---
+
+### 📡 بث السجلات (Log Streaming)
+
+متابعة سجلات التطبيق في الوقت الحقيقي باستخدام الـ Async:
+
+```python
+import asyncio
+
+async def stream_logs():
+    # بث سجلات المخرجات (stdout)
+    async for chunk in client.logs("app-id", "stdout", follow=True):
+        print(chunk.decode('utf-8'), end='')
+
+# تشغيل البث
+asyncio.run(stream_logs())
+```
+
+---
+
+## ⚠️ معالجة الأخطاء (Error Handling)
+
+يقدم الـ SDK استثناء `CuminAPIError` لمعالجة الأخطاء القادمة من الخادم:
+
+```python
+from cumin import CuminClient, CuminAPIError
+
+client = CuminClient(token="your-api-token")
+
+try:
+    project = client.create_project({"name": "my-project"})
+except CuminAPIError as e:
+    print(f"خطأ في الاتصال بالـ API: {e}")
+```
+
+---
+
+## 🏷️ تلميحات الأنواع (Type Hints)
+
+يدعم الـ SDK تلميحات الأنواع (Type Hints) لتحسين تجربة التطوير في الـ IDE والتحقق من الأخطاء:
+
+```python
+from cumin import PostApp, Port, EnvVar
+
+# تعريف بيانات التطبيق بشكل آمن نوعياً
+app_data: PostApp = {
+    "name": "my-app",
+    "instances": 1,
+    "hibernated": False,
+    "image": "nginx:latest",
+    "ports": [Port(name="web", number=80)],
+    "env": [EnvVar(name="NODE_ENV", value="production")],
+    "mounts": []
+}
+```
+
+---
+
+## ⚙️ متغيرات البيئة (Environment Variables)
+
+يمكنك ضبط بعض الإعدادات عبر متغيرات البيئة:
+
+*   `API_URL`: الرابط الأساسي للـ API (القيمة الافتراضية هي `https://api.cumin.dev`).
+
+---
+
+**منصة غيمة** - لتجربة سحابية سلسة وقابلة للبرمجة.