السلسلة: هذا الدرس جزء من سلسلة NestJS 11. اقرأ المقال الرئيسي.

Coolify v4 صار في 2026 PaaS الاستضافة الذاتية المرجع للـ startups التي تريد تجنّب فاتورة Heroku أو Render مع الإبقاء على workflow git push to deploy. هذا الدرس ينشر API NestJS 11 كاملاً على Coolify: VPS Ubuntu، Coolify مثبَّت، Postgres وRedis مُدارَين، Dockerfile multi-stage، نشر من GitHub، شهادات Let Encrypt آلية، نسخ احتياطي مجدول.

المتطلبات

VPS Ubuntu 24.04 LTS بـ 4 جيغا RAM و40 جيغا قرص
اسم نطاق مع وصول DNS
API NestJS 11 في Dockerfile
حساب GitHub مع المستودع
ساعتان

الخطوة 1 — تحضير VPS

sudo apt update && sudo apt upgrade -y
sudo ufw allow OpenSSH
sudo ufw allow http
sudo ufw allow https
sudo ufw allow 6001/tcp
sudo ufw enable
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

المنفذ 6001 واجهة Coolify الإدارية؛ يمكن تقييدها بـ IP مصدر عبر ufw allow from x.x.x.x to any port 6001. أعد جلسة SSH ليُؤخذ مجموعة Docker بعين الاعتبار.

الخطوة 2 — تثبيت Coolify

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

السكربت ينزّل الصور، يضبط docker-compose.yml في /data/coolify، ويُطلق واجهة web على http://<ip>:6001. أول وصول يطلب إنشاء حساب admin. اضبط فوراً: نطاق فرعي مع شهادة Let Encrypt، و2FA على حساب admin.

الخطوة 3 — توصيل GitHub وإنشاء مشروع

Coolify يتصل بـ GitHub عبر GitHub App تُثبَّت ببضع نقرات. هذه App تستقبل webhooks push وتُطلق النشر آلياً.

في Coolify، أنشئ مشروعاً جديداً وأضف مورد Application. اختر GitHub كمصدر، حدّد المستودع وفرع main. Coolify يكتشف Dockerfile أو يقترح Nixpacks. لـ NestJS، Dockerfile متحكَّم به أفضل من Nixpacks.

الخطوة 4 — كتابة Dockerfile multi-stage

# Dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm prune --prod

FROM node:22-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist         ./dist
COPY --from=build /app/prisma       ./prisma
EXPOSE 3000
CMD ["node", "dist/main.js"]

node:22-alpine تسوية حجم/توافق معيارية — Alpine ~150 ميغا مقابل 400+ ميغا لـ Debian. pnpm prune --prod يحذف dependencies التطوير. مجلد prisma/ منسوخ للسماح بتنفيذ npx prisma migrate deploy عند التشغيل.

الخطوة 5 — ضبط متغيّرات البيئة والأسرار

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://acme:****@postgres:5432/acme
REDIS_HOST=redis
REDIS_PORT=6379
JWT_SECRET=<openssl rand -hex 32>
S3_ENDPOINT=https://...r2.cloudflarestorage.com
S3_ACCESS_KEY=...
S3_SECRET_KEY=...
S3_BUCKET=acme-prod

الحيلة المنقذة: ولّد JWT_SECRET بـ openssl rand -hex 32 مباشرة على VPS وألصقه في Coolify. لا تولّده أبداً على آلة تطويرك وتُودعه في مستودع.

الخطوة 6 — توفير Postgres وRedis مُدارَين

أضف مورد Postgres جديد، اختر إصدار 17-alpine. Coolify ينشئ الحاوية، يضبط volume persistance، ويكشف hostname للمشروع عبر شبكة Docker الداخلية. لا منفذ مكشوف على الإنترنت افتراضياً. افعل المثل لـ Redis 8.

الخطوة 7 — ضبط النطاق والشهادات

أشِر نطاقاً فرعياً api.acme.io إلى IP الـ VPS عبر سجل A. في Coolify، أعلن هذا النطاق، فعّل SSL عبر Let Encrypt — Coolify يستخدم Traefik في الخلف.

dig +short api.acme.io
curl -vI https://api.acme.io 2>&1 | grep "issuer"

للـ API المُستهلَكة من front على نطاق آخر، اضبط headers CORS: app.enableCors({ origin: ['https://app.acme.io'] }) في main.ts.

الخطوة 8 — Healthchecks وإعادة تشغيل ونسخ احتياطي

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:3000/health/live || exit 1

إن أخفقت السبر ثلاث مرات، Coolify يُعيد تشغيل الحاوية آلياً. لـ النسخ الاحتياطي، Coolify يُدمج backups مجدولة نحو S3-compatible. اختبر الاستعادة مرة شهرياً.

الخطوة 9 — Pipeline GitHub Actions ونشر zero-downtime

# .github/workflows/deploy.yml
on: { push: { branches: [main] } }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with: { registry: ghcr.io, username: GITHUB_ACTOR, password: GITHUB_TOKEN }
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/acme/api:SHA
      - run: curl -X POST "https://coolify.acme.io/api/v1/deploy?uuid=APP_UUID" -H "Authorization: Bearer TOKEN"

Webhook Coolify يستلم الأمر، يسحب الصورة الجديدة، يُطلق حاوية جديدة بالتوازي، ينتظر مرور healthchecks، ثم يبدّل الحركة. النافذة بضع ثوان — غير مرئية.

أخطاء شائعة

الخطأ	السبب	الحل
Build يفشل بعد push	Lockfile غير متزامن	أعد توليد pnpm-lock محلياً
Migrations Prisma غير مطبَّقة	ترتيب التشغيل مقابل migration	Init container أو أمر pre-deploy
HTTPS غير مُصدَر	DNS لم ينتشر	انتظر + تحقّق `dig`
ذاكرة غير كافية عند build	VPS 2 جيغا	Build خارجي عبر GitHub Actions
سجلات مفقودة	لا driver log بعيد	Loki أو Grafana Cloud sink

أسئلة شائعة

Coolify أم Dokku؟ الاثنان مفتوحان واستضافة ذاتية. Coolify بـ UI حديثة ومجتمع أنشط في 2026.

كم تكلف نشر كامل؟ VPS Hetzner CX23 بـ 3.99 يورو/شهر يدعم API NestJS متواضعة مع Postgres + Redis. Coolify لا تكلفة رخصة — مجاني.

كيف نتوسّع أفقياً؟ Coolify يدعم replicas، لكن load balancing أساسي. للتوسع الجدّي فوق 3-4 نسخ، انتقل إلى Kubernetes أو Nomad.

نشر API NestJS 11 على Coolify v4