استضافة Intlayer ذاتياً

يمكن تشغيل Intlayer بالكامل على بنيتك التحتية الخاصة — دون الحاجة إلى حساب Intlayer Cloud. يُشغّل أمر واحد مكدساً جاهزاً للإنتاج:

أمر واحد يثبت كل شيء:

curl -fsSL https://intlayer.org/install.sh | sh

يقوم المثبّت بتنزيل ملف docker-compose.yml وملف .env، ويولّد الأسرار المطلوبة تلقائياً، ويبدأ تشغيل جميع الحاويات بـ docker compose up -d.

الاعتماد الخارجي الوحيد هو MongoDB: يتصل الـ backend بـ cluster Atlas من MongoDB الذي توفره. كل شيء آخر يعمل داخل الحاوية.

جدول المحتويات

البنية المعمارية

                ┌─────────────────────────────┐
 browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
                └─────────────────────────────┘   │ VITE_BACKEND_URL
                ┌─────────────────────────────┐   │
                │  backend (Fastify/Bun)  :3100│ ◀─┘
                └──────────────┬──────────────┘
          ┌──────────┬─────────┼──────────┬───────────┐
          ▼          ▼         ▼          ▼           ▼
     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium
     (1-node RS)             (S3 API)     (SMTP)        (in-image)
                             minio:9001   mailpit:8025
                             (console)    (web UI)

يتم تضمين Chromium (المستخدم لتوليد لقطات الشاشة عبر Puppeteer) داخل صورة الخادم الخلفي — لا حاجة لحاوية منفصلة.

المتطلبات الأساسية

• Docker ≥ 24 وDocker Compose ≥ v2. إذا كان أحدهما مفقوداً، يطبع المثبّت رابط التثبيت ويخرج.
• المنافذ 3000، 3100، 8025، 9000، و9001 متاحة على المضيف.
• مضيف Linux أو macOS (أو WSL2 على Windows).

كل شيء آخر — Bun و Redis و MinIO و Chromium — يتم شحنه داخل الصورة.

البدء السريع

1. تشغيل المثبِّت

curl -fsSL https://intlayer.org/install.sh | sh

يتحقق من تثبيت Docker وتشغيله، ويكتب ./intlayer.env مع BETTER_AUTH_SECRET و S3_SECRET_ACCESS_KEY التي تم إنشاؤها بالفعل، ويسحب الصورة. لا يبدأ الحاوية — لا يمكن للخادم الخلفي أن يبدأ بدون بيانات اعتماد قاعدة البيانات الخاصة بك.

تشغيل المثبِّت مرة أخرى آمن: لن يتم استبدال intlayer.env الموجود أبدًا، لذا فهو يعمل أيضًا كمسار الترقية.

2. ملء بيانات اعتمادك

افتح intlayer.env وأكمل القيم المشار إليها بـ TODO:

DB_ID=<atlas-user>
DB_MDP=<atlas-password>
DB_CLUSTER=<cluster>.xxxxx.mongodb.net
RESEND_API_KEY=<your-resend-key>

يحتوي الملف أيضًا على كتل معلقة للميزات الاختيارية — SMTP mailer، OPENAI_API_KEY، وموفري OAuth. قم بإلغاء التعليق عما تحتاجه.

يتم قراءة الملف بواسطة docker run --env-file، والذي لا يزيل الاقتباسات ويعامل كل شيء بعد = كقيمة. اكتب القيم بدون اقتباسات، وأبقِ التعليقات على أسطرها الخاصة.

3. بدء الحاوية

هذا هو الأمر الذي يطبعه المثبِّت عند انتهائه:

docker run -d --name intlayer \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 3100:3100 \
  -p 9000:9000 \
  -p 9001:9001 \
  -v intlayer-data:/data \
  --env-file ./intlayer.env \
  ghcr.io/aymericzip/intlayer-selfhost:latest

ثم افتح http://localhost:3000. يقوم الإقلاع الأول بتهيئة مخازن البيانات، لذا امنحه دقيقة واحدة.

لوحة التحكم موجودة على localhost. انظر القيود — النطاقات المخصصة غير مدعومة في الصورة المنشورة.

إعدادات المثبت

يقرأ المثبت بعض متغيرات البيئة. لأنه موجه إلى sh، مرر هذه المتغيرات إلى shell بدلاً من تمريرها إلى curl:

curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh

متغيرات المنافذ الأربعة تغير فقط الجانب المضيف من التعيين المطبوع في أمر docker run. الصورة المنشورة لديها http://localhost:3000 و http://localhost:3100 و http://localhost:9000 مدرجة في حزمة لوحة التحكم في وقت البناء، لذا فإن إعادة تعيينها تترك المتصفح يشير إلى المنافذ القديمة. احتفظ بالقيم الافتراضية إلا إذا كنت تقوم بإنشاء صورتك الخاصة — انظر القيود.

إعداد التشغيل الأول

على نسخة جديدة (قاعدة بيانات فارغة)، يعيد فتح لوحة التحكم توجيهك إلى صفحة /init:

1. أنشئ الحساب الأول. نظراً لأن مجموعة المستخدمين فارغة، يتم ترقية هذا الحساب تلقائياً إلى super admin.
2. يتم إرسال بريد إلكتروني للتحقق (عبر Resend). التحقق من البريد الإلكتروني إلزامي — وهذا هو السبب في أنه يجب تعيين RESEND_API_KEY قبل أن تبدأ.
3. انقر على الرابط في البريد الإلكتروني، ثم قم بتسجيل الدخول.

بمجرد وجود admin، يعيد /init التوجيه إلى صفحة تسجيل الدخول القياسية.

الخدمات

يجب أن يكون منفذ MinIO 9000 قابلاً للوصول من المتصفح لأن الأصول المرفوعة (الصور الرمزية، لقطات الشاشة) تُحمَّل مباشرة من S3_PUBLIC_URL=http://localhost:9000/intlayer.

متغيرات البيئة

مطلوب

المطلوبة (مولّدة تلقائياً أو مطلوبة)

اختيارية (تتدهور الميزات بشكل سلس عند غيابها)

بريد عام

بشكل افتراضي، يتم إرسال جميع رسائل البريد الإلكترونية للمعاملات عبر Resend باستخدام RESEND_API_KEY. يمكن للنشرات ذاتية الاستضافة بدلاً من ذلك توجيه كل بريد إلكتروني — بما في ذلك رسائل البريد الإلكترونية غير المتعلقة بالمنظمة مثل إعادة تعيين كلمات المرور والروابط السحرية — عبر بريد عام مُعد باستخدام متغيرات البيئة.

عيّن MAIL_PROVIDER لتفعيله. عند عدم التعيين، يتم استخدام بريد Resend الافتراضي.

الأولوية: بريد المنظمة الخاص بها (المُعد من لوحة المعلومات Organization) له الأولوية على البريد العام، والذي له بدوره الأولوية على مفتاح Resend الافتراضي.

ربط مشروعك بـ Intlayer

بمجرد تشغيل المكدس، وجّه مشروعك نحو الخادم الخلفي ولوحة التحكم المستضافَين ذاتياً بدلاً من intlayer.org.

تهيئة المشروع

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,

    /**
     * عنوان URL للوحة تحكم CMS المستضافة ذاتياً.
     * الافتراضي: https://app.intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000

    /**
     * عنوان URL لواجهة برمجة تطبيقات الخادم الخلفي المستضافة ذاتياً.
     * الافتراضي: https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
  },
};

export default config;

اضبط متغيرات البيئة في ملف .env الخاص بمشروعك:

INTLAYER_CMS_URL=http://localhost:3000
INTLAYER_BACKEND_URL=http://localhost:3100
INTLAYER_CLIENT_ID=<your-client-id>
INTLAYER_CLIENT_SECRET=<your-client-secret>

أنشئ بيانات اعتماد الوصول في لوحة التحكم المستضافة ذاتياً ضمن المشاريع ← مفاتيح الوصول على http://localhost:3000/projects.

SDK الخاص بـ @intlayer/api

عند استخدام SDK الخاص بـ @intlayer/api برمجياً، مرّر backendURL بشكل صريح:

import { createIntlayerCMS } from "@intlayer/api";
import { dictionaryEndpoint } from "@intlayer/api/dictionary";

const cms = createIntlayerCMS({
  editor: {
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
  },
});

const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();

الترقية

يجلب هذا الأمر أحدث الصور ويعيد تشغيل الحاويات باستخدام docker compose pull && docker compose up -d. يتم الاحتفاظ بالأحجام الموجودة (mongo-data، redis-data، minio-data) — دون فقدان للبيانات.

docker compose pull
docker compose up -d

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

تعيش جميع البيانات الدائمة في ثلاثة أحجام Docker مسماة.

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

docker run --rm \
  -v intlayer_mongo-data:/data \
  -v "$(pwd)":/backup \
  busybox tar czf /backup/mongo-data.tar.gz /data

docker run --rm \
  -v intlayer_redis-data:/data \
  -v "$(pwd)":/backup \
  busybox tar czf /backup/redis-data.tar.gz /data

docker run --rm \
  -v intlayer_minio-data:/data \
  -v "$(pwd)":/backup \
  busybox tar czf /backup/minio-data.tar.gz /data

الاستعادة

docker run --rm \
  -v intlayer_mongo-data:/data \
  -v "$(pwd)":/backup \
  busybox tar xzf /backup/mongo-data.tar.gz -C /

# كرر لـ redis-data و minio-data

القيود

• MongoDB يجب أن يكون خارجياً (Atlas). يتصل الخادم الخلفي فقط عبر mongodb+srv:// (مبني من DB_ID / DB_MDP / DB_CLUSTER)، لذا لا يمكن استخدام mongodb://host:27017 العادي — بما في ذلك mongod المدمج في الحاوية الخاصة — لا يمكن استخدامه. قدم مجموعة MongoDB Atlas.
• لا توجد نطاقات مخصصة. جميع عناوين URL الموجهة للمتصفح VITE_* مدرجة مباشرة في التطبيق وقت البناء، والصورة المنشورة تأتي مع قيم localhost. يجب الوصول إلى لوحة التحكم على http://localhost:3000؛ تقديمها على نطاق عام سيتطلب إعادة بناء الصورة مع عناوين URL المستهدفة المدمجة فيها وليس مدعوماً بشكل افتراضي.
• البريد الإلكتروني يتطلب خادم بريد يعمل. إعداد التشغيل الأول يفرض التحقق من البريد الإلكتروني، لذا يجب تكوين إما RESEND_API_KEY أو خادم SMTP عام (MAIL_PROVIDER=smtp + MAIL_SMTP_*). بعد دخول المسؤول الأول، يمكن لكل منظمة أيضاً تكوين خادم SMTP أو Resend الخاص بها من لوحة التحكم.

استكشاف الأخطاء وإصلاحها

الخادم الخلفي يتعطل عند الإقلاع

يجب أن يكون MongoDB وRedis في حالة صحية قبل بدء تشغيل الخادم الخلفي. يستخدم ملف compose depends_on مع condition: service_healthy. إذا رأيت إعادات تشغيل متكررة للخادم الخلفي، تحقق من اجتياز فحوصات صحة mongo وredis:

docker compose ps
docker compose logs mongo
docker compose logs redis

ابحث عن MongoDB connection error بالقرب من أعلى السجل.

لوحة التحكم لا تستطيع الوصول إلى API

تحقق من أن VITE_BACKEND_URL يطابق عنوان URL حيث يمكن الوصول إلى الخادم الخلفي من المتصفح (ليس شبكة Docker). إذا غيّرت منفذ الخادم الخلفي أو أضفت وكيلاً عكسياً، أعد بناء صورة لوحة التحكم:

دلو MinIO مفقود

إذا لم تُشغَّل خدمة minio-init المؤقتة (أو شُغّلت قبل أن يكون MinIO جاهزاً)، أنشئ الدلو يدوياً:

docker compose run --rm minio-init

روابط مفيدة

• توثيق Intlayer CMS
• مرجع التهيئة
• CMS SDK — @intlayer/api
• Docker Image (aymercizip/intlayer-selfhost)