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 على الماك — كله يشتغل داخل الحاويات.

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

```bash
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

```bash
git pull
./start.sh rebuild
```

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

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

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

   ```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`.

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

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

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

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