تثبيت Coolify لنشر التطبيقات من Git على خادمك

عندما تريد نشر تطبيق صغير لفريقك على السيرفر Server، فسوف تجد أنك تكرر نفس الخطوات في كل مرة: تكتب ملف Compose، ثم تضبط الـ Reverse Proxy، ثم تطلب شهادة TLS، ثم تكتب سكربت Script للنسخ الاحتياطي Backup، وكل تطبيق جديد يعني تكرار هذه الخطوات من البداية. والحل المعروف لهذه المشكلة هو منصات مثل Heroku وVercel وNetlify التي تقوم بكل ذلك مقابل اشتراك شهري، ولكن الكود والبيانات تبقى على سيرفرات غيرك، والفاتورة تكبر كلما كبر المشروع، أما الحل الآخر فهو منصة من نفس النوع تثبتها على سيرفرك أنت، وهذا ما يقدمه Coolify.

Coolify منصة كخدمة Platform as a Service واختصاراً PaaS، مفتوحة المصدر Open Source وتعمل على سيرفرك، حيث تعطيها رابط مستودع Repository في Git فتقوم ببناء التطبيق ونشره Deployment داخل Container، وتربطه تلقائياً بنطاق Domain وشهادة من Let's Encrypt، وتشغل أيضاً قواعد البيانات Databases وتجدول نسخها الاحتياطية إلى تخزين متوافق مع S3، وتدير أكثر من سيرفر عبر SSH من لوحة تحكم Dashboard واحدة. والمشروع منشور برخصة Apache 2.0 على GitHub.

وهذه المنصة تناسب الفريق الذي يطور تطبيقاته بنفسه ويريد نشراً سهلاً دون أن يرتبط بمزود سحابي معين، وتناسب أيضاً مدير تقنية المعلومات IT Manager الذي يهمه أمران: أن تصبح التكلفة هي ثمن السيرفر وحده، وأن تبقى البيانات في مركز البيانات الذي يختاره هو.

وسوف نناقش في هذا المقال ما يلي:

• متى تحتاج Coolify ومتى يكفيك Portainer.
• تجهيز السيرفر، ثم التثبيت بالسكربت الرسمي بعد قراءته وليس بتنفيذه مباشرة من الإنترنت، مع إنشاء حساب المدير أثناء التثبيت.
• ربط لوحة التحكم بنطاق وشهادة HTTPS، ثم إغلاق المنافذ المؤقتة.
• إضافة سيرفر بعيد، ونشر تطبيق من Git، وخدمة جاهزة، ومتغيرات البيئة، وقواعد البيانات ونسخها المجدولة.
• النسخ الاحتياطي لـ Coolify نفسه واستعادته على سيرفر جديد، والتحديث بإصدار تختاره أنت، وأشهر المشكلات وحلولها.

متى يناسبك Coolify ومتى يكفيك Portainer؟

كثيرون يخلطون بين الأداتين، فكلتاهما تعمل فوق Docker ولها واجهة ويب Web UI، ولكن الفرق الحقيقي في نقطة البداية، فـ Portainer يدير ما هو موجود أصلاً من الـ Containers والـ Images والـ Volumes وملفات Compose التي تكتبها بنفسك، أما Coolify فيبدأ من الكود المصدري Source Code، فيبني التطبيق ثم يتولى كل ما حوله من النطاق والشهادة والنسخ الاحتياطي، والجدول التالي يبين الفرق:

لذلك اختر Coolify إذا كان فريقك ينشر تطبيقات يكتبها بنفسه، وتريد أن يضغط المطور زر Deploy دون أن يطلب منك ضبط النطاق في كل مرة، واكتف بـ Portainer مع Nginx Proxy Manager إذا كانت خدماتك برامج جاهزة تشغلها من ملفات Compose. وإذا أردت مقارنة أوسع تضم Dokploy أيضاً فراجع مقارنة Portainer وCoolify وDokploy.

المتطلبات

• سيرفر نظيف بنظام Ubuntu 24.04 LTS لا يعمل عليه أي تطبيق آخر، فـالوثائق الرسمية توصي بسيرفر جديد حتى لا يحدث تعارض مع التطبيقات الموجودة، وإذا كنت ما زلت تبحث عن سيرفر فراجع كيف تختار خادماً افتراضياً VPS.
• الموارد Resources: الحد الأدنى الرسمي معالجان 2 CPU cores و2 جيجابايت من الذاكرة RAM و10 جيجابايت مساحة حرة على القرص Disk، بمعمارية Architecture من نوع amd64 أو arm64، وهذا يكفي Coolify نفسه فقط، ولكن بناء التطبيقات على نفس السيرفر يستهلك الذاكرة بسرعة، لذلك ابدأ بـ 4 جيجابايت إذا كنت سوف تبني من الكود المصدري.
• صلاحية root: السكربت الرسمي يعمل بحساب root أو عبر sudo، ويرفض العمل بغير ذلك.
• نطاق تدير سجلات DNS Records الخاصة به: سجل A للوحة التحكم مثل coolify.example.com، وإن أردت سجل wildcard للتطبيقات مثل *.example.com، وكلاهما يشير إلى عنوان السيرفر 203.0.113.10.
• المنافذ Ports: 22 للإدارة، و80 و443 للـ Proxy، و8000 و6001 و6002 للوحة التحكم مؤقتاً حتى تربطها بالنطاق، والتفاصيل في قسم جدار الحماية Firewall.

جهز السيرفر قبل التثبيت

إذا اتبعت دليل تأمين خادم VPS من أول دخول فأنت قد عطلت دخول root عبر SSH، ولكن Coolify يتصل حتى بالسيرفر الذي يعمل عليه عبر SSH بحساب root وبمفتاح ينشئه بنفسه، لذلك نسمح لـ root بالدخول بالمفتاح وحده دون كلمة مرور Password، كما يشرح دليل OpenSSH في الوثائق، فقم بتعديل الملف /etc/ssh/sshd_config ليحتوي هذين السطرين:

PubkeyAuthentication yes
PermitRootLogin prohibit-password

والقيمة prohibit-password تعني أن root يدخل بمفتاح SSH فقط، أما محاولات الدخول بكلمة المرور فترفض، وبالتالي يبقى السيرفر محمياً من تخمين كلمات المرور Brute Force مع أن Coolify يستطيع الاتصال. وقبل إعادة تشغيل الخدمة تحقق من صحة الإعداد، وأبق جلستك الحالية مفتوحة حتى تتأكد أن الدخول ما زال يعمل:

sudo sshd -t
sudo systemctl restart ssh

أما جدار الحماية فهناك نقطة يقع فيها كثيرون، وهي أن Docker يتجاوز قواعد ufw للمنافذ التي ينشرها، فإذا أغلقت المنفذ 8000 بـ ufw فهو في الحقيقة لم يغلق، لذلك استخدم جدار الحماية الذي يقدمه مزود السيرفر في لوحته، والسبب أنه يحجب الطلبات قبل أن تصل إلى السيرفر أصلاً، وإذا لم يتوفر عند المزود فـالوثائق تقترح أداة ufw-docker.

ولا تحتاج إلى تثبيت Docker مسبقاً، فالسكربت يثبته من get.docker.com، وإذا كان مثبتاً عندك وفق دليل تثبيت Docker على Ubuntu فسوف يتحقق السكربت فقط من أن إصداره 24 أو أحدث، أما Docker المثبت عبر snap فلا يدعمه Coolify، ويتوقف السكربت إذا وجده.

التثبيت (Installation) بالسكربت الرسمي

الإصدار المستقر Stable الحالي هو Coolify 4.3.23 الذي صدر في 18 سبتمبر 2026، وفي ملف الإصدارات الرسمي تجد رقم الإصدار المستقر في الحقل v4 ورقم الإصدار التجريبي في الحقل nightly، وهو حالياً 4.4-rc.1، فلا تخلط بينهما.

والطريقة التي تعرضها الوثائق هي تنفيذ السكربت مباشرة بالأمر curl ... | bash، وهي أسرع طريقة بالطبع، ولكن المشكلة فيها أنك تشغل كوداً من الإنترنت بصلاحية root لم تقرأ منه سطراً واحداً، وهذا السكربت تحديداً يعدل إعدادات Docker على سيرفرك ويضيف مفتاحاً إلى حساب root. وقد يتساءل البعض: إذا كان السكربت من المشروع الرسمي فما الفائدة من قراءته؟ والإجابة أنك سوف تعرف بالضبط ما الذي تغير في سيرفرك وأين، وهذا ما سوف تحتاجه لاحقاً عند النسخ الاحتياطي والاستعادة وحل المشكلات، كما أنك تثبت رقم الإصدار الذي راجعته بدلاً من أي إصدار يكون هو الأحدث لحظة التنفيذ. لذلك ننزل السكربت أولاً ونقرؤه، ثم ننفذه.

ماذا يفعل السكربت؟

curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o install.sh
less install.sh

وعند قراءة السكربت سوف تجد أنه ينفذ تسع خطوات ويطبعها بالترتيب:

1. يثبت الحزم Packages التي يحتاجها: curl وwget وgit وjq وopenssl.
2. يتحقق من وجود خادم OpenSSH ومن إعداد PermitRootLogin.
3. يثبت Docker Engine عبر get.docker.com إذا لم يجده، ويشترط الإصدار 24 على الأقل.
4. يكتب الملف /etc/docker/daemon.json ويضع فيه حداً لحجم السجلات Logs هو 10 ميجابايت لثلاثة ملفات، ونطاق عناوين لشبكات Docker هو 10.0.0.0/8، وإذا كان الملف موجوداً فإنه يحتفظ بنسخة من الأصل.
5. ينزل ملفات Compose من شبكة توزيع المحتوى CDN الخاصة بالمشروع إلى /data/coolify/source.
6. ينشئ ملف .env.
7. يولد فيه أسراراً Secrets عشوائية أهمها APP_KEY.
8. ينشئ مفتاح SSH في /data/coolify/ssh/keys ويضيفه إلى ~/.ssh/authorized_keys لحساب root، ثم يحذف ملف المفتاح العام .pub ويبقي المفتاح الخاص وحده، وهذا يحدث في التثبيت الأول فقط.
9. يشغل Coolify عبر upgrade.sh، ثم يطبع رابط لوحة التحكم على المنفذ 8000.

ولاحظ أن كل ما يخص Coolify موجود تحت /data/coolify: الملفات المصدرية في source، والمفاتيح في ssh، وإعداد الـ Proxy في proxy، والنسخ الاحتياطية في backups.

تشغيل السكربت مع حساب مدير جاهز

بعد التثبيت مباشرة تظهر صفحة التسجيل Registration، وتبقى مفتوحة لأي زائر حتى ينشأ الحساب الأول، ومن يسجل أولاً يصبح مدير المنصة، وهذا يعني أنه يملك صلاحية root على سيرفرك عبر مفتاح SSH الذي أنشأه السكربت. لذلك تسمح الوثائق بإنشاء حساب المدير أثناء التثبيت عبر ثلاثة متغيرات بيئة Environment Variables، فلا تظهر صفحة التسجيل أبداً، ونمرر معها رقم الإصدار حتى نثبت نفس الإصدار الذي راجعناه:

sudo env ROOT_USERNAME=admin \
  [email protected] \
  ROOT_USER_PASSWORD='Ch@nge-This-Passw0rd' \
  bash install.sh 4.3.23

في الإعداد أعلاه لاحظ التالي:

• يتحقق Coolify من صيغة البريد الإلكتروني ومن وجود سجلات DNS صالحة لنطاقه، لذلك ضع بريدك الحقيقي وليس example.com.
• كلمة المرور 8 أحرف على الأقل، فيها حرف كبير وحرف صغير ورقم ورمز، ولا تكون من كلمات المرور المسربة المعروفة.
• إذا لم تستوف القيم هذه الشروط فإن Coolify يتجاهلها ولا ينشئ الحساب، وتعود صفحة التسجيل مفتوحة، لذلك تحقق في الخطوة التالية من أنك تدخل بها فعلاً.
• يحفظ السكربت هذه القيم كما هي في /data/coolify/source/.env، فغير كلمة المرور من لوحة التحكم بعد الدخول الأول، وتذكر أن الأمر الذي يبدأ بمسافة في Ubuntu لا يحفظ في سجل الطرفية Shell History.

ويستغرق التثبيت بضع دقائق بحسب سرعة السيرفر والشبكة، وفي النهاية يطبع السكربت الرسالة Your instance is ready to use! ومعها الرابط http://203.0.113.10:8000، وينبهك إلى حفظ ملف .env في مكان آمن خارج السيرفر.

إذا أردت أن تنفذ الخطوات بنفسك Manual Installation

إذا كانت سياسة مؤسستك تمنع تشغيل سكربتات من الإنترنت بصلاحية root، فـالوثائق تشرح تثبيتاً يدوياً تنفذ فيه كل خطوة بنفسك، وشرطه أن يكون Docker Engine 24 أو أحدث مثبتاً مسبقاً. والأوامر التالية من الوثائق، فنفذها بحساب root:

mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}
mkdir -p /data/coolify/ssh/{keys,mux}
mkdir -p /data/coolify/proxy/dynamic

ssh-keygen -f /data/coolify/ssh/keys/[email protected] -t ed25519 -N '' -C root@coolify
cat /data/coolify/ssh/keys/[email protected] >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml
curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh -o /data/coolify/source/upgrade.sh

chown -R 9999:root /data/coolify
chmod -R 700 /data/coolify

بعد ذلك قم بتوليد الأسرار مرة واحدة فقط، والسبب أن تغييرها لاحقاً يتلف التثبيت كله، فـ APP_KEY مثلاً هو المفتاح الذي تشفر به كل الأسرار المحفوظة في قاعدة البيانات:

sed -i "s|APP_ID=.*|APP_ID=$(openssl rand -hex 16)|g" /data/coolify/source/.env
sed -i "s|APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|g" /data/coolify/source/.env
sed -i "s|DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sed -i "s|REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sed -i "s|PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sed -i "s|PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sed -i "s|PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|g" /data/coolify/source/.env

وهنا أيضاً تستطيع إضافة الأسطر ROOT_USERNAME وROOT_USER_EMAIL وROOT_USER_PASSWORD إلى ملف .env حتى تنشئ حساب المدير مسبقاً، ثم أنشئ الشبكة وشغل Coolify:

docker network create --attachable coolify
docker compose --env-file /data/coolify/source/.env -f /data/coolify/source/docker-compose.yml -f /data/coolify/source/docker-compose.prod.yml up -d --pull always --remove-orphans --force-recreate

ولاحظ أن الطريقة اليدوية لا تعدل /etc/docker/daemon.json، لذلك اضبط حد حجم السجلات بنفسك إذا لم يكن مضبوطاً، حتى لا يمتلئ القرص بعد أسابيع من التشغيل.

الدخول الأول وتأمين الحساب

افتح الرابط http://203.0.113.10:8000 وادخل بالبريد وكلمة المرور اللذين مررتهما للسكربت، وإذا لم تنشئ الحساب مسبقاً فسوف تظهر لك صفحة التسجيل، فأنشئ الحساب فوراً ولا تؤجله، كما تحذر الوثائق.

بعد ذلك فعل التحقق بخطوتين Two-Factor Authentication لحسابك من صفحة الملف الشخصي Profile، كما يشرح دليل 2FA، والسبب أن هذا الحساب يتحكم في كل السيرفرات المتصلة بالمنصة، فمن يحصل على كلمة المرور وحدها يحصل على root في كل مكان.

ثم يعرض Coolify معالج الإعداد Onboarding، فاختر فيه This machine، وبهذا يستخدم السيرفر نفسه بيئة نشر باسم localhost، وهذا مناسب في البداية، ولكن Coolify نفسه ينبه إلى أن هذا الخيار لا يناسب أحمال الإنتاج Production Workloads، والسبب أن المنصة وعمليات البناء والتطبيقات تتقاسم موارد سيرفر واحد، لذلك انقل التطبيقات المهمة لاحقاً إلى سيرفر بعيد كما سوف نشرح.

اربط لوحة التحكم بنطاق وشهادة HTTPS

أضف لدى مزود DNS سجل A للاسم coolify.example.com يشير إلى 203.0.113.10، وتحقق من انتشاره بالأمر dig +short coolify.example.com، ثم افتح Settings واختر Configuration ثم General، واكتب في حقل URL العنوان كاملاً مع البروتوكول:

https://coolify.example.com

واحفظ بالزر Save changes، فيقوم Coolify بضبط الـ Proxy ليوجه هذا النطاق إلى لوحة التحكم، ويطلب له شهادة من Let's Encrypt عبر المنفذ 80. وشروط هذا العنوان مذكورة في صفحة إعدادات المنصة: نطاق أو نطاق فرعي Subdomain دون مسار مثل /coolify، ولا يستخدمه أي تطبيق آخر في المنصة، وأبق خيار Redirect HTTP to HTTPS مفعلاً.

وإذا أردت أن يقترح Coolify لكل تطبيق جديد نطاقاً فرعياً Subdomain تلقائياً، فافتح Servers ثم localhost واكتب في حقل Wildcard Domain القيمة https://example.com، ويلزمك لذلك سجل *.example.com يشير إلى السيرفر.

وعندما يفتح https://coolify.example.com بشهادة صحيحة، وتعمل التحديثات اللحظية Real-time والطرفية Terminal في الواجهة، أغلق المنافذ 8000 و6001 و6002 كما في القسم التالي.

أي المنافذ تبقى مفتوحة بعد ضبط النطاق؟

صفحة جدار الحماية في الوثائق تحدد المنافذ التالية للسيرفر الذي يعمل عليه Coolify:

فبعد ضبط النطاق تمر لوحة التحكم والتحديثات اللحظية والطرفية كلها عبر المنفذين 80 و443، ولا يبقى سبب لترك المنافذ الثلاثة مفتوحة. والطريقة البديهية لإغلاقها هي تعديل ملف docker-compose.prod.yml نفسه، ولكن هذا الحل لا يصمد، والسبب أن كل تحديث لـ Coolify يستبدل هذا الملف بنسخة جديدة من الـ CDN فيضيع تعديلك دون أن تنتبه. والطريقة الصحيحة هي ملف إضافي Override لا يلمسه التحديث، تجعل فيه Coolify ينشر هذه المنافذ على 127.0.0.1 فقط، وبهذا تحصل على طبقة حماية ثانية لا تعتمد على جدار المزود. أنشئ الملف /data/coolify/source/docker-compose.custom.yml:

services:
  coolify:
    ports: !override
      - "127.0.0.1:${APP_PORT:-8000}:8080"
  soketi:
    ports: !override
      - "127.0.0.1:${SOKETI_PORT:-6001}:6001"
      - "127.0.0.1:6002:6002"

في الإعداد أعلاه لاحظ التالي:

• الوسم !override يجعل Compose يستبدل قائمة المنافذ كاملة بدلاً من دمجها مع القائمة الأصلية، ولولاه لبقي المنفذ منشوراً على كل العناوين بجانب السطر الجديد.
• الخدمة soketi هي الـ Container الذي يظهر باسم coolify-realtime، وهي التي تخدم المنفذين 6001 و6002.
• بقاء المنافذ على 127.0.0.1 يعني أنك تستطيع الوصول إليها دائماً عبر نفق SSH إذا تعطل الـ Proxy.

وقبل التطبيق تحقق أن Compose يقبل الملف:

cd /data/coolify/source
sudo docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml config > /dev/null && echo OK

ثم أعد تشغيل Coolify بسكربت التحديث مع رقم الإصدار المثبت حالياً، فالسكربت يقرأ docker-compose.custom.yml تلقائياً إذا وجده:

curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | sudo bash -s 4.3.23

أما السيرفرات البعيدة التي يديرها Coolify فيكفيها المنفذ 22 مفتوحاً لعنوان سيرفر Coolify وحده، والمنفذان 80 و443 إذا كانت تستقبل زواراً، ولا تفتح منفذ قاعدة بيانات للإنترنت إلا لعناوين محددة تحتاج إليه.

إدارة السيرفر المحلي وسيرفر بعيد عبر SSH

السيرفر المحلي localhost

افتح Servers ثم localhost، ويجب أن تراه بالحالة Reachable وValidated، وأن ترى في تبويب Proxy أن coolify-proxy يعمل، وإذا ظهر متوقفاً فاضغط Start Proxy. وهذا يعني أن Coolify يتصل بنفس السيرفر عبر SSH بالمفتاح الذي أنشأه السكربت، وهذا هو سبب إعداد PermitRootLogin الذي ضبطناه في البداية.

إضافة سيرفر بعيد Remote Server

يدير Coolify أي عدد من السيرفرات من لوحة واحدة، فتنشر التطبيقات على سيرفر الإنتاج وتبقي المنصة نفسها على سيرفر صغير مستقل، وهذه خطوات إضافة سيرفر:

1. افتح Keys & Tokens ثم Private Keys ثم + Add، واختر Generate new ED25519 SSH Key، واكتب اسماً للمفتاح، وانسخ المفتاح العام Public Key، ولا تضع له عبارة مرور Passphrase، والسبب أن Coolify يستخدمه دون تدخل منك.
2. على السيرفر البعيد 203.0.113.20 أضف المفتاح العام سطراً جديداً في /root/.ssh/authorized_keys، واضبط PermitRootLogin prohibit-password كما فعلت عند تجهيز السيرفر:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

3. في Coolify افتح Servers ثم + Add ثم Manual، واكتب الاسم والعنوان 203.0.113.20 دون https://، والمنفذ 22، والمستخدم root، ثم اختر المفتاح.
4. اضغط Validate Server & Install Docker Engine، فيختبر Coolify اتصال SSH، ويثبت Docker إن لم يجده، ثم يشغل الـ Proxy على ذلك السيرفر.

ويسمح Coolify أيضاً بالاتصال بحساب غير root له صلاحية sudo دون كلمة مرور، ولكن الوثائق تصف هذا الخيار بأنه تجريبي، وتنبه إلى أن هذا الحساب يبقى فعلياً بصلاحيات root، فلا تعتبره طبقة حماية إضافية.

نشر تطبيق من مستودع Git عام

ينظم Coolify العمل في مشاريع Projects، وفي كل مشروع بيئات Environments مثل production، وفي كل بيئة موارد Resources وهي التطبيقات وقواعد البيانات والخدمات. ولنأخذ مثالاً بسيطاً بـ Node.js من مستودع الأمثلة الرسمي:

1. من Projects أنشئ مشروعاً جديداً مثل demo، وافتح البيئة production.
2. اضغط + New واختر Public Repository، ثم اختر السيرفر localhost.
3. الصق رابط المستودع عبر HTTPS وليس عبر SSH، ثم اضغط Check Repository، وتأكد أن الفرع Branch هو main:

https://github.com/coollabsio/coolify-examples.git

4. في Build Pack اختر Nixpacks، واكتب في Base Directory المسار /javascript/runtimes/nodejs، وفي Ports Exposes المنفذ 3000 لأن التطبيق يستمع عليه.
5. اكتب في حقل Domains العنوان https://app.example.com، أو اترك النطاق الذي اقترحه Coolify إن كنت ضبطت Wildcard Domain، ثم اضغط Deploy وتابع سجل البناء حتى ينتهي.

وNixpacks يعرف نوع المشروع من ملفاته، فعندما يرى package.json يبني Image تشغل npm start دون أن تكتب أنت Dockerfile، وإذا كان في مستودعك Dockerfile أو ملف Compose فاختر الـ Build Pack المناسب، والفروق بينها في صفحة طرق البناء. وهناك خطأ شائع هنا، وهو أنك إذا كتبت النطاق دون منفذ فإن Coolify يوجه الطلبات إلى المنفذ 80 داخل الـ Container، فإذا كان تطبيقك يستمع على 3000 فسوف تحصل على خطأ Bad Gateway مع أن البناء نجح، لذلك اضبط Ports Exposes على المنفذ الذي يستمع عليه تطبيقك، كما تشرح صفحة النطاقات.

ولاحظ أن المستودع العام لا ينشر تلقائياً مع كل Commit، فإذا أردت ذلك فأضف Webhook في مستودعك، أو اربط Coolify بـ GitHub App للمستودعات الخاصة.

تشغيل خدمة جاهزة بنقرة واحدة

في Coolify قائمة من الخدمات الجاهزة One-click Services، وهي قوالب Templates من ملفات Compose يحدثها فريق المشروع لبرامج مثل Umami وUptime Kuma وGitea وNextcloud، فمن نفس المشروع اضغط + New وابحث عن Umami مثلاً واختره.

وسوف يولد Coolify كلمات المرور اللازمة في متغيرات البيئة، ويقترح للخدمة نطاقاً بالصيغة https://stats.example.com:3000، والمنفذ في هذا الحقل يخبر Coolify بالمنفذ داخل الـ Container فلا تحذفه، أما الزائر فيفتح https://stats.example.com دون منفذ، ثم اضغط Deploy.

متغيرات البيئة والأسرار

افتح التطبيق ثم Configuration ثم Environment Variables، وسوف تجد لكل متغير خيارين مستقلين كما توضح صفحة متغيرات البيئة: Build Variable ليكون متاحاً أثناء البناء، وRuntime Variable ليكون متاحاً في الـ Container أثناء التشغيل، ومن Developer view تستطيع لصق عدة قيم دفعة واحدة بصيغة .env:

NODE_ENV=production
LOG_LEVEL=info
API_URL=https://api.example.com

• عطل Build Variable لأي سر لا يحتاجه التطبيق إلا بعد التشغيل مثل كلمة مرور قاعدة البيانات، والسبب أن متغيرات البناء قد تظهر في البيانات الوصفية Metadata للـ Image، أما الأسرار التي يحتاجها البناء فعلاً مثل توكن Token لمستودع حزم خاص ففعل لها Use Docker Build Secrets.
• فعل Literal للقيم التي فيها $، حتى لا يفسرها Coolify كمرجع لمتغير آخر.
• القيمة المشتركة بين عدة تطبيقات، مثل رابط قاعدة البيانات، عرفها مرة واحدة كمتغير مشترك Shared Variable على مستوى الفريق أو المشروع أو البيئة، ثم أشر إليها بالصيغة {{environment.DATABASE_URL}}.
• بعد تعديل المتغيرات: إذا تغيرت متغيرات البناء فأعد النشر، وإذا تغيرت متغيرات التشغيل فقط فيكفي Restart.

ويشفر Coolify هذه القيم ومفاتيح SSH بالمفتاح APP_KEY قبل أن يحفظها في قاعدة بياناته، وسوف نعود إلى أهمية هذا المفتاح في قسم النسخ الاحتياطي.

قواعد البيانات ونسخها المجدولة إلى S3

من + New اختر قاعدة بيانات مثل PostgreSQL أو MySQL أو MariaDB أو MongoDB أو Redis، فينشئ Coolify كلمة المرور ويعرض رابط الاتصال الداخلي Internal URL لتضعه في متغيرات بيئة تطبيقك، ولا يمكن الوصول إلى قاعدة البيانات من الإنترنت إلا إذا فعلت لها منفذاً عاماً بنفسك.

والنسخة المحفوظة على نفس السيرفر لا تحميك إذا تعطل السيرفر نفسه أو حذف، لذلك أنشئ أولاً وجهة تخزين خارجية، أي مخزن كائنات Object Storage متوافقاً مع S3 مثل Amazon S3 أو Cloudflare R2 أو Backblaze B2 أو MinIO:

1. أنشئ الـ Bucket لدى المزود أولاً، ومعه مفتاح وصول Access Key مقصور عليه.
2. في Coolify افتح S3 Storages ثم Add، واكتب Endpoint واسم الـ Bucket والمنطقة Region والمفتاحين، ثم اضغط Validate Connection & Continue، كما تشرح صفحة تخزين S3.

بعد ذلك افتح قاعدة البيانات واختر Backups، واضغط + Add بجانب Scheduled Backups، واكتب الجدولة Schedule بصيغة cron مثل 0 3 * * * لنسخة يومية في الثالثة فجراً، أو بإحدى القيمتين daily وhourly، ثم فعل S3 واختر الوجهة التي أنشأتها. واضبط مدة الاحتفاظ Retention للنسخ المحلية ولنسخ S3، فلكل منهما إعداد مستقل، ثم اضغط Backup Now لتجربة فورية، وتحقق في Executions أن الحالة Success وأن حجم الملف أكبر من صفر.

والنسخ المجدولة تدعم PostgreSQL وMySQL وMariaDB وMongoDB وClickHouse، ولا تدعم Redis وDragonfly وKeyDB. وتذكر أن النسخة الناجحة لا تضمن استعادة ناجحة، لذلك جرب من حين لآخر استعادة نسخة في قاعدة بيانات تجريبية.

التحقق من النجاح (Verification)

• كل Containers المنصة تعمل وحالتها healthy:

sudo docker ps --format "table {{.Names}}\t{{.Status}}"

NAMES              STATUS
coolify-proxy      Up 2 hours (healthy)
coolify            Up 2 hours (healthy)
coolify-realtime   Up 2 hours (healthy)
coolify-db         Up 2 hours (healthy)
coolify-redis      Up 2 hours (healthy)

• لوحة التحكم تستجيب من السيرفر نفسه:

curl -s http://127.0.0.1:8000/api/health

OK

• يفتح https://coolify.example.com بشهادة صادرة عن Let's Encrypt، ويظهر رقم الإصدار 4.3.23 في أعلى القائمة الجانبية.
• يظهر localhost وأي سيرفر بعيد بالحالة Validated في صفحة Servers.
• يفتح https://app.example.com ويعيد التطبيق استجابته، ويفتح المسار /health بالنص OK.
• من جهاز خارجي لا يستجيب المنفذ 8000، فالأمر nc -zv -w 5 203.0.113.10 8000 ينتهي بانتهاء المهلة Timeout أو برفض الاتصال.

النسخ الاحتياطي والاستعادة (Restore)

لنفرض أن سيرفر Coolify توقف نهائياً، فما الذي تحتاجه لتعيد المنصة كما كانت على سيرفر جديد؟ تحتاج ثلاثة أشياء: الأول قاعدة بيانات Coolify نفسه وفيها المشاريع والإعدادات والسيرفرات والأسرار، والثاني APP_KEY من ملف .env، فبدونه لا يستطيع Coolify قراءة الأسرار المشفرة في قاعدة البيانات المستعادة، والثالث مفاتيح SSH في /data/coolify/ssh/keys وبها يتصل بالسيرفرات. ولاحظ أن بيانات تطبيقاتك وقواعد بياناتها ليست في هذه النسخة، فلها نسخها المجدولة التي ضبطتها في القسم السابق.

النسخ الاحتياطي

من الواجهة افتح Settings ثم Backup، واضغط Configure Backup في المرة الأولى، فيفعل Coolify نسخة يومية لقاعدة بياناته، ثم فعل S3 Enabled واختر وجهة S3، كما تشرح صفحة نسخ المنصة. أما النسخة اليدوية من الطرفية فتكون بالأمر pg_dump داخل الـ Container coolify-db:

sudo mkdir -p /data/backups
sudo docker exec coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify | sudo tee /data/backups/coolify-db-$(date +%F).dmp > /dev/null
sudo test -s /data/backups/coolify-db-$(date +%F).dmp && sudo ls -lh /data/backups/

بعد ذلك اضغط ملف .env ومفاتيح SSH في أرشيف واحد:

sudo tar czf /data/backups/coolify-files-$(date +%F).tar.gz -C /data/coolify source/.env ssh/keys

ثم انقل الملفين إلى خارج السيرفر، واحفظ سطر APP_KEY وحده أيضاً في مدير كلمات المرور Password Manager، والسبب أن نسخ S3 تحمل قاعدة البيانات وحدها دون هذا المفتاح:

sudo grep '^APP_KEY=' /data/coolify/source/.env

الاستعادة على خادم جديد

الخطوات التالية من صفحة الاستعادة الرسمية، فثبت أولاً على السيرفر الجديد نفس الإصدار الذي أخذت منه النسخة، بالسكربت ورقم الإصدار، وتأكد أن لوحة التحكم الجديدة تفتح، ثم انسخ ملف النسخة إليه وأوقف كل Containers المنصة ما عدا قاعدة البيانات:

export BACKUP_PATH=/data/backups/coolify-db-2026-10-01.dmp
sudo test -s "$BACKUP_PATH" && ls -lh "$BACKUP_PATH"
sudo docker stop coolify coolify-redis coolify-realtime

افتح /data/coolify/source/.env واستبدل قيمة APP_KEY وحدها بالقيمة المحفوظة، أما بقية القيم مثل DB_PASSWORD فهي تخص التثبيت الجديد فلا تغيرها، ثم استعد قاعدة البيانات:

sudo docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < "$BACKUP_PATH"

بعد ذلك احذف المفاتيح التي أنشأها التثبيت الجديد وضع مكانها المفاتيح الأصلية من الأرشيف، ثم أضف المفتاح العام الأصلي إلى /root/.ssh/authorized_keys على السيرفر الجديد، ولاحظ أننا نستخرج المفتاح العام من المفتاح الخاص بالأمر ssh-keygen -y، والسبب أن سكربت التثبيت يحذف ملف .pub بعد إنشاء المفتاح كما رأينا عند قراءته، فلن تجده في الأرشيف:

sudo rm -f /data/coolify/ssh/keys/*
sudo tar xzf /data/backups/coolify-files-2026-10-01.tar.gz -C /tmp ssh/keys
sudo cp /tmp/ssh/keys/* /data/coolify/ssh/keys/
sudo ssh-keygen -y -f /data/coolify/ssh/keys/[email protected] | sudo tee -a /root/.ssh/authorized_keys > /dev/null

ثم شغل السكربت مرة أخرى بنفس الإصدار، فيعيد تشغيل Coolify ويعيد ضبط ملكية الملفات تحت /data/coolify، ويطبق ترحيلات Migrations قاعدة البيانات إن لزم:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash -s 4.3.23

وبعد ذلك تحقق أن لوحة التحكم تفتح دون خطأ تشفير، وأن المشاريع موجودة، وأن localhost والسيرفرات البعيدة تجتاز التحقق، ثم غير سجل DNS للوحة التحكم ليشير إلى العنوان الجديد.

التحديث (Upgrade) إلى إصدار أحدث

افتراضياً يحدث Coolify نفسه تلقائياً، حيث يفحص ملف الإصدارات كل ساعة ويثبت الإصدار الجديد يومياً في منتصف الليل، وقد يبدو هذا مريحاً من الوهلة الأولى، ولكن المشكلة فيه أن المنصة التي تدير كل سيرفراتك سوف تتغير في منتصف الليل دون أن تقرأ ملاحظات الإصدار ودون نسخة احتياطية قبلها، وإذا تعطل شيء فسوف تكتشفه في الصباح. لذلك هذا الإعداد مقبول على سيرفر التجارب، أما في بيئة الإنتاج Production فالحل الأنسب هو التحديث بإصدار محدد تختاره أنت وفي الوقت الذي تختاره. ولتعطيل التحديث التلقائي افتح Settings ثم Configuration ثم Updates، واضبط Automatic updates على Disabled، وتستطيع تعطيله أثناء التثبيت أيضاً بتمرير AUTOUPDATE=false للسكربت، ولاحظ أن هذا المتغير إذا وجد في .env فإنه يغلب على إعداد الواجهة، فلا تستطيع تغييره من هناك.

وبعد تعطيل التحديث التلقائي لا تؤجل التحديثات إلى أجل غير مسمى، وإنما تابع صفحة الإصدارات والتنبيهات الأمنية للمشروع، وطبق إصلاحات الثغرات خلال أيام وليس أشهر.

وقبل أي تحديث، كما توصي صفحة التحديث الرسمية:

1. راجع صفحة الإصدارات، والتزم بالإصدارات المستقرة وليس الإصدارات المرشحة Release Candidates مثل 4.4-rc.1.
2. أنشئ نسخة احتياطية من قاعدة بيانات Coolify كما في القسم السابق.
3. تأكد أنه لا توجد عمليات نشر جارية، والسبب أنها تفشل إذا أعيد تشغيل Coolify أثناءها.

ثم حدث من الواجهة بالزر Upgrade Now في صفحة Updates، أو من الطرفية بسكربت التحديث مع رقم الإصدار الجديد دون الحرف v:

curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | sudo bash -s 4.3.23

ولا تحذف رقم الإصدار، والسبب أن السكربت بدونه يكتب COOLIFY_VERSION=latest في .env فيتعطل فحص التحديثات، ولا تستخدم install.sh لتحديث منصة قائمة، لأنه يعيد ضبط ملكية الملفات وصلاحياتها تحت /data/coolify ومنها بيانات الخدمات. ويستغرق التحديث عادة أقل من دقيقة تتوقف فيها لوحة التحكم، أما التطبيقات والـ Proxy فتبقى تعمل، وإذا لم تعد اللوحة فاقرأ سجلات التحديث في /data/coolify/source/upgrade-*.log.

مشكلات شائعة وحلولها (Troubleshooting)

الـ Proxy لا يبدأ: المنفذ 80 أو 443 محجوز

إذا ظهر في سجل الـ Proxy خطأ مثل address already in use فهذا يعني أن خدمة أخرى تستمع على نفس المنفذ، ويمكنك معرفتها بالأمر التالي:

sudo ss -ltnp '( sport = :80 or sport = :443 )'

فإذا كان Nginx أو Apache مثبتاً من حزم النظام فعطله بالأمر sudo systemctl disable --now nginx، وإذا كان Container آخر مثل Nginx Proxy Manager فالحل الصحيح أن تنقل Coolify إلى سيرفر مستقل، وليس أن تشغل اثنين من الـ Reverse Proxy على نفس المنفذين. وبعد ذلك افتح Servers ثم localhost ثم Proxy، واضغط Start Proxy.

البناء يفشل أو يتجمد الخادم أثناءه

بناء تطبيقات Node.js وأمثالها يستهلك الذاكرة بكثرة، فإذا نفدت الذاكرة أوقف النظام العملية وظهر في السجل رمز الخروج Exit Code 137، أو توقف السيرفر عن الاستجابة تماماً. وفي صفحة المشكلة في الوثائق ثلاثة حلول: أن تزيد ذاكرة السيرفر، أو تنقل البناء إلى سيرفر بناء Build Server مستقل، أو تبني الـ Image في CI مثل GitHub Actions وتنشرها في Coolify جاهزة من Docker Image، وراقب الاستهلاك أثناء البناء بالأمر htop.

النطاق لا يحصل على شهادة

في هذه الحالة يعرض المتصفح شهادة موقعة ذاتياً Self-signed من الـ Proxy، وفي صفحة المشكلة في الوثائق الأسباب الشائعة:

• السجل A لا يشير إلى السيرفر بعد، وتتحقق من ذلك بالأمر dig +short app.example.com.
• المنفذ 80 مغلق في جدار المزود، وهو ضروري للتحقق من ملكية النطاق عبر HTTP أي HTTP Challenge.
• سجل AAAA يشير إلى عنوان IPv6 لا يصل إلى السيرفر، فاحذفه إذا كنت لا تستخدم IPv6.
• النطاق يمر عبر Proxy خارجي مثل Cloudflare بوضع Proxied، فيعترض طلبات التحقق.
• كثرت المحاولات ففرضت Let's Encrypt حداً عليها، فإذا رأيت الرمز 429 في سجل الـ Proxy فانتظر قبل أن تحاول مجدداً.

وبعد إصلاح السبب أعد نشر التطبيق، وإذا كانت ملفات الشهادات المحفوظة تالفة فاحذف الملف /data/coolify/proxy/acme.json ثم اضغط Restart Proxy من صفحة السيرفر.

لا تفتح لوحة التحكم

جرب أولاً الدخول عبر المنفذ 8000 من نفق SSH، فإذا فتحت اللوحة عبره ولم تفتح عبر النطاق فالمشكلة في الـ Proxy، فشغله من صفحة السيرفر واقرأ سجله في تبويب Logs، وإذا كنت عدلت إعداده فأعده إلى الافتراضي. أما إذا لم تفتح عبر المنفذ 8000 أيضاً فتحقق من حالة الـ Containers بالأمر sudo docker ps وأعد تشغيل المتوقف منها، كما تشرح صفحة المشكلة في الوثائق. وإذا كنت تستخدم ufw-docker فتأكد أن القاعدة لا تشير إلى عنوان IP قديم للـ Container coolify، والسبب أن عنوانه قد يتغير بعد كل تحديث.

خطأ The MAC is invalid بعد الاستعادة

هذا الخطأ يعني أن APP_KEY في .env ليس هو المفتاح الذي شفر به Coolify قاعدة البيانات المستعادة، فأوقف الـ Container coolify، وضع القيمة المحفوظة في .env، ثم شغل السكربت مرة أخرى بنفس الإصدار. وإذا فقدت المفتاح الأصلي فلن تستطيع قراءة الأسرار والمفاتيح المحفوظة، وعليك أن تدخلها من جديد، وهذا سبب إصرارنا على حفظ APP_KEY خارج السيرفر.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

• Coolify يناسب الفريق الذي ينشر تطبيقات يكتبها من Git، أما البرامج الجاهزة من ملفات Compose فيكفيها Portainer مع Reverse Proxy.
• ثبته على سيرفر نظيف، واقرأ السكربت قبل تنفيذه، وثبت رقم الإصدار، وأنشئ حساب المدير أثناء التثبيت حتى لا تبقى صفحة التسجيل مفتوحة.
• بعد ربط لوحة التحكم بالنطاق أغلق المنافذ 8000 و6001 و6002 من جدار المزود، أو انشرها على 127.0.0.1 عبر docker-compose.custom.yml وليس بتعديل ملفات Compose الأصلية.
• حساب Coolify يعادل root على كل سيرفراتك، ففعل 2FA وطبق إصلاحات الثغرات بسرعة، ولكن بتحديث تختار أنت إصداره ووقته وليس بالتحديث التلقائي.
• الاستعادة تحتاج قاعدة البيانات وAPP_KEY ومفاتيح SSH معاً، فاحفظها كلها خارج السيرفر، وجرب الاستعادة قبل أن تحتاجها.

سجل التحديثات (Changelog)

• أكتوبر 2026: كتابة الدليل ومراجعته على Coolify 4.3.23، وتصحيح خطوة استعادة مفاتيح SSH لأن سكربت التثبيت لا يبقي ملف المفتاح العام .pub.