استضافة Cal.com على VPS: دليل Docker الشامل

‎Cal.com‎ تطبيق ‎Next.js‎ يعتمد على ‎PostgreSQL‎ يتولّى جدولة المواعيد وأنواع الأحداث وأوقات التوفّر والمزامنة مع التقاويم (‎Google‎ و‎CalDAV‎ و‎Office 365‎). تلبّي الاستضافة الذاتية حاجة محدّدة: التحكم في بيانات توفّر عملائك وحجز مواعيدهم، التي تمرّ عادةً عبر خدمة أمريكية طرف ثالث. على خادم ‎VPS‎، تلغي قيود الخطة المجانية (نوع حدث واحد، علامة تجارية مفروضة)، وتربط مفاتيح ‎API‎ الخاصة بك لـ‎Google‎/الاجتماعات المرئية، وتضمّن أداة الحجز مباشرةً في موقعك تحت نطاقك. وبما أن ‎Cal.com‎ تطبيق ‎Node‎ دائم مع قاعدة بيانات وبناء إنتاجي، فإنه يتطلّب خادم ‎VPS‎ — إذ لا تستطيع الاستضافة المشتركة تشغيل العملية ولا استضافة ‎PostgreSQL‎.

‎Cal.com‎ أكثر تطلّبًا من متوسط الاستضافة الذاتية بسبب أساسه ‎Next.js‎ وخطوة البناء. خصّص 2 ‎vCPU‎ و4 غيغابايت من ‎RAM‎ و20 غيغابايت من القرص لنسخة فريق مريحة؛ وقد يكفي 2 غيغابايت من ‎RAM‎ للاستخدام الفردي لكن البناء الأولي يكون أضيق. تحتاج إلى ‎Docker‎ و‎Docker Compose‎، وقاعدة بيانات ‎PostgreSQL‎ (مشمولة في ملف ‎compose‎ الرسمي)، ونطاق rdv.yourdomain.com موجَّه إلى الخادم ‎VPS‎، وعدة متغيرات بيئة إلزامية: NEXTAUTH_SECRET وCALENDSO_ENCRYPTION_KEY (مفاتيح مولَّدة عشوائيًا) وNEXT_PUBLIC_WEBAPP_URL مضبوطًا على عنوان ‎HTTPS‎ النهائي. وللمزامنة مع التقويم والاجتماعات المرئية، جهّز معرّفات ‎OAuth‎ الخاصة بـ‎Google‎.

يستمع ‎Cal.com‎ على المنفذ 3000 داخل الحاوية. وكيل عكسي بـ‎HTTPS‎ مطلوب لسببين: كشف المنفذ 443 وإعادة توجيه رأس Host الصحيح — وإلا فإن NEXT_PUBLIC_WEBAPP_URL لن يطابق الأصل الفعلي وستنهار عمليات إعادة توجيه المصادقة.

باستخدام ‎Caddy‎ (موصى به، شهادة تلقائية):

rdv.yourdomain.com {
    reverse_proxy calcom:3000
}

يحصل ‎Caddy‎ على شهادة ‎Let's Encrypt‎ ويجدّدها دون إعداد إضافي.

باستخدام ‎nginx‎، أضِف هذه الكتلة إلى إعداداتك:

server {
    listen 443 ssl;
    server_name rdv.yourdomain.com;
    ssl_certificate     /etc/letsencrypt/live/rdv.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/rdv.yourdomain.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

في كلتا الحالتين، يجب أن يطابق الرابط NEXT_PUBLIC_WEBAPP_URL تمامًا: بدون شرطة مائلة في النهاية، بـ‎HTTPS‎، مع النطاق الفرعي الصحيح. أي فارق في حرف واحد ينتج حلقات إعادة توجيه لا تنتهي أو شاشة بيضاء.

ثلاثة متغيرات بيئة مُقيَّدة نهائيًا عند أول تشغيل لـ‎Cal.com‎. تغييرها لاحقًا يُفسد صامتًا جميع التكاملات المخزّنة: يُعيد التطبيق تشغيله بصورة طبيعية ولا يُظهر أي خطأ، لكن ‎Google Calendar‎ و‎Zoom‎ وجميع اتصالات ‎OAuth‎ تتوقف عن العمل — إذ خُزِّنت رموزها المشفَّرة بالمفتاح الأصلي غير المتوافق الآن. هذا السلوك موثَّق في calcom/docker issue #333 وcalcom/cal.diy issue #13290: فقد مستخدمون جميع تكاملاتهم إثر تحديث أعاد إنشاء ملف .env.

CALENDSO_ENCRYPTION_KEY — يشفّر رموز ‎OAuth‎ المخزّنة في قاعدة البيانات. أي تعديل يُلغي صامتًا جميع التكاملات القائمة.

NEXTAUTH_URL — يثبّت ملفات تعريف الارتباط للجلسة. أي تغيير يُعطل المصادقة لجميع المستخدمين النشطين.

NEXT_PUBLIC_WEBAPP_URL — مضمَّن في بناء ‎Next.js‎ وقت الترجمة. تغيير هذه القيمة يستلزم إعادة بناء كاملة وإعادة توصيل جميع التكاملات.

أفضل الممارسات: انسخ هذه القيم الثلاث فورًا إلى مدير الأسرار (‎Bitwarden‎، ‎HashiCorp Vault‎، ‎Ansible Vault‎). وإن كنت تدير خادمك بنهج البنية التحتية كرمز (‎infrastructure-as-code‎)، خزّنها في قبو مشفَّر — لا تجعل ملف .env موضعها الوحيد.

‎CLIENT_FETCH_ERROR‎ عند تحميل الصفحة — منذ مطلع 2026، تواجه جميع تثبيتات ‎Docker‎ الجديدة هذا الخطأ عند أول تحميل. السبب: تحاول حاوية ‎Next.js‎ حلّ NEXTAUTH_URL (نطاقك العام) من داخل شبكة ‎Docker‎، حيث لا يمكن الوصول إلى ‎DNS‎ الخارجي. الحل: أضِف NEXTAUTH_URL_INTERNAL=http://calcom:3000 إلى ملف .env وأعِد التشغيل بـdocker compose up -d. هذا المتغير يُجبر ‎NextAuth‎ على استدعاء واجهته الخاصة داخليًا دون المرور بالنطاق العام. موثَّق في calcom/cal.diy issue #27668 (فبراير 2026، 8 تعليقات تؤكد الخطأ في جميع توزيعات ‎Docker‎ الحديثة).

ضياع التكاملات بعد تحديث — السبب في الغالب CALENDSO_ENCRYPTION_KEY مختلفة بين تشغيلَين. تحقق من أن ملف .env لم يُستبدَل بـ.env.example أثناء التنزيل. قارن القيمة الحالية بتلك المحفوظة في مدير الأسرار. إن اختلفتا: استعِد قاعدة بيانات ‎PostgreSQL‎، أعِد المفتاح الأصلي إلى .env، وأعِد التشغيل بـdocker compose up -d.

خطأ «JavaScript heap out of memory» أثناء البناء — المُجمِّع ‎Next.js‎ يعاني من نقص ‎RAM‎. الحل: fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile، ثم أعِد تشغيل docker compose build. على خادم ‎VPS‎ بسعة 2 غيغابايت، الـ‎swap‎ ضروري غالبًا للبناء الأول والتحديثات الكبرى. أزِل ملف الـ‎swap‎ بعد اكتمال البناء.

حلقة إعادة توجيه أو خطأ «Unable to find valid origin» — NEXT_PUBLIC_WEBAPP_URL لا يطابق الرابط الفعلي. تحقق من أن هذا المتغير يساوي بالضبط https://rdv.yourdomain.com (بدون شرطة مائلة في النهاية، بالنطاق الصحيح وبروتوكول ‎HTTPS‎)، وأن الوكيل العكسي يُعيد توجيه رأس Host بصورة صحيحة، ثم أعِد التشغيل بـdocker compose up -d --build لإجبار إعادة البناء بالرابط الصحيح.

عمليات ترحيل ‎Prisma‎ متعلّقة عند بدء التشغيل — إن أعادت الحاوية تشغيلها باستمرار مع أخطاء ترحيل، قد لا تكون قاعدة البيانات جاهزة بعد. انتظر بضع ثوانٍ وشغّل docker compose restart calcom. وإن استمرت المشكلة، تحقق من سجلات ‎PostgreSQL‎ بـdocker compose logs db.

بمجرد تشغيل ‎Cal.com‎، ثمة خطوات لتعزيز التثبيت: تفعيل تنبيهات شهادات ‎SSL‎ لتوقّع انتهاء صلاحيتها، وإعداد مراقبة ‎HTTP‎ (‎Uptime Kuma‎، ‎Better Uptime‎) على https://rdv.yourdomain.com/api/health، وتقييد منفذ الحاوية 3000 على 127.0.0.1 لمنع الوصول المباشر إليه. وللتثبيتات الجماعية، يمكن للوكيل العكسي خدمة عدة نسخ من ‎Cal.com‎ خلف نطاقات فرعية متمايزة من خادم ‎VPS‎ واحد — راجع النشر باستخدام ‎Coolify‎ لإدارة متعددة الخدمات مبسَّطة. تغطّي وثائق ‎Cal.com‎ الرسمية أيضًا إعداد ‎SMTP‎ لرسائل التأكيد وتكامل ‎Stripe‎ للحجوزات المدفوعة.