TX/DOCKER.md

تشغيل Tx OS عبر Docker

دليل سريع لتشغيل المشروع بالكامل على جهازك (ماك / لينكس) بأمر واحد، بدون الحاجة لتثبيت Node أو Postgres يدوياً.

المتطلبات

• Docker Desktop (الإصدار 4.x أو أحدث) — حمّله من https://www.docker.com/products/docker-desktop/.
  • يدعم Apple Silicon (M1/M2/M3/M4) و Intel.
  • تأكد إنه شغّال بعد التثبيت (تشوف أيقونة الحوت بأعلى الشاشة).
• Git — موجود غالباً، تأكد بـ git --version.

لا تحتاج تثبيت Node أو pnpm أو Postgres على الماك — كله يشتغل داخل الحاويات.

التشغيل لأول مرة

git clone https://desktop-11cj93j.tail866923.ts.net/rafraa/TX.git
cd TX
./start.sh

السكربت يعمل تلقائياً:

1. ينشئ ملف .env من .env.docker.example ويولّد SESSION_SECRET و POSTGRES_PASSWORD عشوائيين.
2. يبني صور Docker (أول مرة يأخذ 5–10 دقائق — Node, Chromium, dependencies).
3. يشغّل Postgres ثم يدفع جداول قاعدة البيانات (drizzle-kit push) ثم يزرع البيانات الأولية (seed).
4. يشغّل API server والواجهة خلف Nginx.

بعدها افتح: http://localhost:3000

بيانات الدخول الأولى

أول مرة يشغّل فيها start.sh يطبع لك كلمتي مرور عشوائيتين في الترمنال (وكمان يحفظهن في .env):

Admin login:   admin / <كلمة سر عشوائية>
User login:    ahmed / <كلمة سر عشوائية>

انسخهن فوراً. لو فقدت كلمة سر admin تحتاج تدخل قاعدة البيانات يدوياً لإعادة تعيينها. تقدر تغيّرها لاحقاً من لوحة الإدارة داخل التطبيق.

الأوامر اليومية

الأمر	الوظيفة
./start.sh	تشغيل (build إذا لزم)
./start.sh logs	متابعة سجلّات الحاويات
./start.sh stop	إيقاف بدون حذف (البيانات تبقى)
./start.sh down	حذف الحاويات (البيانات تبقى في الـ volumes)
./start.sh rebuild	إعادة بناء الصور من الصفر
./start.sh reset	خطر: حذف قاعدة البيانات والملفات المرفوعة

البنية

http://localhost:3000  →  nginx (web container)
                          ├── /            → ملفات React الثابتة
                          └── /api/*       → http://api:8080 (Node Express + Socket.IO)
                                              └── postgres:5432
                                              └── /app/storage (volume للملفات)

ثلاث حاويات + قاعدة بيانات:

• postgres — Postgres 16، البيانات في volume اسمه tx-os_postgres_data.
• migrate — يشتغل مرة وحدة عند كل تشغيل، يدفع schema ويزرع البيانات.
• api — Node 24 + Chromium (لتوليد PDF) + التخزين المحلي.
• web — Nginx يقدّم الواجهة ويعمل reverse proxy للـ API.

تخصيص

عدّل .env بعد ما يُنشأ. أهم القيم:

• APP_PORT=3000 — منفذ المتصفح (غيّره مثلاً إلى 8080 لو 3000 محجوز).
• SESSION_SECRET — سر توقيع الجلسات (مولّد تلقائياً، لا تشاركه).
• POSTGRES_PASSWORD — كلمة مرور قاعدة البيانات.
• STORAGE_DRIVER=local — التخزين على القرص داخل الحاوية (افتراضي ومناسب لمعظم الحالات).
• SMTP_* — إعدادات البريد لإشعارات اجتماعات الإدارة (اختياري).

بعد تعديل .env نفّذ ./start.sh stop ثم ./start.sh لإعادة التحميل.

استكشاف الأخطاء

• المنفذ 3000 محجوز: عدّل APP_PORT في .env.
• الواجهة ما تفتح: راجع ./start.sh logs، خصوصاً سجل api و migrate.
• بحاجة للوصول لقاعدة البيانات: docker compose exec postgres psql -U tx tx.
• مساحة القرص: docker system prune يحذف الصور غير المستخدمة (لا يلمس الـ volumes).

التحديث من Gitea

git pull
./start.sh rebuild

تنبيه التحديثات (System Updates)

صفحة Admin → System Updates تعرض الإصدار الحالي وتقدر تفحص لو في إصدار أحدث على Gitea. للتفعيل:

1. تأكد أن ملف latest.json موجود في جذر الريبو على Gitea بنفس بنية version.json:

   { "version": "0.2.0", "build": "20260601.abc1234" }
   

2. أضف في .env (أو docker-compose.yml تحت services.api.environment):

   LATEST_VERSION_URL=https://desktop-11cj93j.tail866923.ts.net/rafraa/TX/raw/branch/main/latest.json
   

3. أعد التشغيل: ./start.sh stop && ./start.sh.

عند كل إصدار جديد: حدّث latest.json في الريبو وادفع. عملاء Tx OS سيرون شارة "Update available" عند ضغطهم على Check Now.

رقم البناء (build) يُولَّد تلقائياً من git قبل كل pnpm run build (انظر scripts/update-version.mjs)، فلا تحتاج تعديله يدوياً في version.json.

تفعيل تطبيقي التقويم والإشعارات

افتراضياً يصلان مُعطَّلَين في البيئات الجديدة. لتفعيلهما على بيئة موجودة (مرة واحدة):

docker compose exec api pnpm --filter @workspace/scripts run enable-default-apps

السكربت idempotent (آمن لإعادة التشغيل) ويعيد فقط is_active=true لـ calendar و notifications.