# نشر منصة الأولمبياد المتميزة على VPS

دليل تشغيلي كامل — من خادم فارغ إلى https://olympiads.online
(نفس نهج جدوى: Docker Compose + Caddy بشهادات تلقائية).

## المتطلبات

- **VPS** بنظام Ubuntu 22.04+ ‏(1–2GB RAM تكفي — SQLite بلا خدمات ثقيلة).
- توجيه DNS: سجل A لـ `olympiads.online` (و`www` إن رغبت) إلى IP الخادم.

## 1) تهيئة الخادم (مرة واحدة)

```bash
apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
apt install -y git
ufw allow OpenSSH && ufw allow 80 && ufw allow 443 && ufw --force enable
```

## 2) جلب المشروع والأسرار

```bash
git clone <رابط مستودعك> /opt/olympiads && cd /opt/olympiads
cp .env.example .env
nano .env
```

القيم الإلزامية في `.env` للإنتاج:

```
OLYMPIADS_DOMAIN=olympiads.online
ADMIN_PASSWORD=<كلمة قوية — دخول لوحة التحرير>
SESSION_SECRET=<openssl rand -base64 32>
```

> ملاحظة: `DATABASE_URL` يضبطه compose تلقائياً إلى الحجم الدائم
> `file:/app/data/olympiads.db` — لا تضعه في `.env` الإنتاجي.

## 3) الإقلاع الأول

```bash
docker compose -f docker-compose.prod.yml up -d --build
```

- الحاوية تنفّذ `prisma db push` تلقائياً عند كل إقلاع (مزامنة مخطط آمنة).
- شهادة HTTPS تصدر تلقائياً من Caddy خلال ثوانٍ بعد صحة DNS.

ثم افتح `https://olympiads.online/admin`، ادخل بكلمة `ADMIN_PASSWORD`،
واضغط **«استيراد بذور الحزمة العلمية»** مرة واحدة — يعبّئ الأطلس (30 فكرة)
والمسائل الست المعتمدة كبذرة إطلاق منشورة.

## 4) التحديثات اللاحقة

```bash
cd /opt/olympiads && git pull
docker compose -f docker-compose.prod.yml up -d --build
```

قاعدة البيانات في حجم دائم (`appdata`) — لا يمسّها إعادة البناء.

## 5) النسخ الاحتياطي والاستعادة

- خدمة `backup` تأخذ نسخة يومية 03:00 بتوقيت الرياض إلى `./backups/`
  وتبقي آخر 14 يوماً.
- استعادة يدوية:

```bash
docker compose -f docker-compose.prod.yml stop web
docker run --rm -v olympiads_appdata:/data -v $(pwd)/backups:/b alpine \
  cp /b/olympiads-<التاريخ>.db /data/olympiads.db
docker compose -f docker-compose.prod.yml start web
```

## 6) خارطة التوسعة

- **PostgreSQL**: عند نمو البيانات — بدّل provider في `prisma/schema.prisma`
  إلى postgresql، حوّل أعمدة `*_json` إلى `Json`، أضف خدمة postgres في compose
  (انظر qudurat-platform كمرجع)، ثم `prisma migrate`. طبقة المحوّلات في
  `src/lib/content-db.ts` لا تتغير.
- **الدفع (ميسر)**: باقات الاشتراك لكل مسار معرّفة في الواجهة والمخططات
  (`Entitlement` في schemas.json)؛ ربط Moyasar يتبع نفس نمط جدوى
  (مفاتيح sk_live/pk_live + webhook).
- **مصحح الرُبريك بالذكاء الاصطناعي والمصحح المعزول للكود**: خدمات مستقلة
  وفق العقد الصارم في `algorithms.md` §5–§6.

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

| العرض | السبب الأرجح | العلاج |
| --- | --- | --- |
| شهادة HTTPS لا تصدر | DNS لم ينتشر بعد | `dig olympiads.online` ثم أعد تشغيل caddy |
| 401 في لوحة التحرير | كلمة/جلسة | تحقق من `ADMIN_PASSWORD` وأعد الدخول |
| المسائل لا تظهر من القاعدة | لم تُستورد البذور | زر الاستيراد في /admin |
| فقدان بيانات بعد إعادة بناء | حذف الحجم يدوياً | استعد من `./backups/` |