تثبيت Quire باستخدام Docker Compose

ثبّت Quire على بنيتك التحتية باستخدام Docker Compose.

هذا هو المنتج الكامل على مضيف واحد: نظام إدارة التعلم، وأعماله الخلفية، وخدمات الوقت الحقيقي والتحرير التعاوني، وكل خدمة اختيارية خلف ملف تعريف. يشرح docs/architecture/23-ops.md القسم 2 التصميم.

تشغّل البيئات الأخرى طبقة الويب فقط: Vercel وCloudflare Workers. تجد الترقية في upgrade.md، والنسخ الاحتياطي وتمرين الاستعادة في backup-restore.md.

المتطلبات

Docker Engine 27 أو أحدث مع إضافة Compose 2.30 أو أحدث.
4 أنوية CPU و8 GB من الذاكرة للحزمة الافتراضية؛ و8 أنوية و16 GB مع --profile full (يستهلك ClamAV وحده نحو 1.5 GB من التواقيع).
اسم DNS لطبقة الويب وآخر للمحتوى غير الموثوق. يجب أن يكونا على مضيفين مختلفين: تعمل حزم SCORM وHTML المرفوع على أصل المحتوى كي لا تتمكن مطلقًا من قراءة ملفات تعريف ارتباط نظام إدارة التعلم.
للاختبار المحلي، يحل lvh.me و*.localhost إلى 127.0.0.1، وهو ما يستخدمه docker/.env.example. وتقدم خدمة proxy في الحزمة كلا العنوانين عبر https بشهادة محلية، لذا لا يلزم تثبيت شيء آخر (راجع «TLS»).
يجب أن يكون المنفذان 80 و443 متاحين على المضيف (غيّر القيمتين QUIRE_PROXY_HTTP_PORT وQUIRE_PROXY_HTTPS_PORT لنقلهما).

التشغيل الأول

QUIRE_APP_ORIGIN=https://learn.example.org \
QUIRE_CONTENT_ORIGIN=https://content.example-content.org \
QUIRE_SETUP_ADMIN_EMAIL=you@example.org \
  docker/scripts/init-env.sh
docker compose -f docker/compose.yaml up -d --build
docker compose -f docker/compose.yaml logs init

ينشئ docker/scripts/init-env.sh ملف docker/.env من docker/.env.example ويولّد كل الأسرار (كلمات مرور قواعد البيانات ومفاتيح التوقيع والمفتاح الرئيسي وزوج مفاتيح تشغيل المحتوى)، كما ينشئ مفتاح توقيع نقاط تدقيق الحفظ في docker/secrets/audit-signing-key.pem، الذي يركبه Compose في العمال كسر. لا يحتاج إلا sh وawk وopenssl ويرفض الكتابة فوق docker/.env موجود. انسخ الملفين إلى خارج المضيف: لا تستطيع قاعدة البيانات المستعادة فك تشفير بيانات الاعتماد دون QUIRE_MASTER_KEY. ولملء الملف يدويًا، نفذ cp docker/.env.example docker/.env؛ إذ يوضح الملف كيفية إنشاء كل سر.

يجب أن يبدأ العنوانان بـhttps: ترفض خدمة المحتوى استخدام http الصريح في الإنتاج، ولا يجوز أن يشتركا في نطاق قابل للتسجيل نفسه. تنهي خدمة proxy تشفير TLS لكليهما (راجع «TLS»)، ويرفض init-env.sh العنوان الذي يبدأ بـhttp://.

تبدأ الخدمات بترتيب ثابت، وتنتظر كل خطوة السابقة:

تصبح postgres سليمة. وفي التشغيل الأول يضبط نص الإعداد (docker/postgres/init/90-passwords.sh) كلمات مرور الأدوار الأربع.
تطبق migrate كل عمليات الترحيل وتجهز قائمة المهام في قاعدة التحكم وكل قاعدة مستأجر مخصصة، وتتحقق من تطابقها، ثم تنتهي (docs/ops/upgrade.md). تعمل الترحيلات مع كل بدء وهي قابلة للتكرار، لذا تكون الترقية صورة جديدة وإعادة تشغيل.
تسجل init (apps/web/src/first-run.ts) قاعدة بيانات التطبيق تحت QUIRE_DATABASE_ID، وتنشئ المؤسسة الأولى ومسؤولها إذا عُيّن QUIRE_SETUP_ADMIN_EMAIL. يُطبع عنوان تسجيل الدخول وكلمة المرور المولدة مرة واحدة في docker compose logs init.
تبدأ web وcontent وworker وscheduler وcollab وcentrifugo.
تبدأ proxy بعد تحقق سلامة web وcontent.

افتح https://demo. ملحقًا بنطاق التطبيق (يعرض سجل init عنوان الدخول الدقيق)، ثم سجل الدخول. في التثبيت المحلي، وثق بسلطة شهادات الوكيل أولًا (راجع «TLS»). وغيّر كلمة المرور المولدة في /account/security.

يرفض أي إجراء لا يبدأ بسر مطلوب البدء ويسمي الإعداد المفقود في سجله. ولا يبدأ شيء بإعداد ناقص.

الخدمات وملفات التعريف

الخدمة	ملف التعريف	وظيفتها
postgres	دائمًا	قاعدة البيانات (PostgreSQL 18 مع pgvector، مبنية من `docker/postgres.Dockerfile`)، مع أرشفة WAL من أول تشغيل
migrate, init	دائمًا	تشغيل لمرة واحدة: الترحيلات ثم الإعداد الأول
web	دائمًا	نظام إدارة التعلم على `QUIRE_HTTP_PORT` (8080)
content	دائمًا	أصل المحتوى غير الموثوق على `QUIRE_CONTENT_PORT` (8081)
worker	دائمًا	المهام الخلفية: البريد والتقارير ومعالجة الملفات وخطافات الويب
scheduler	دائمًا	المهام المتكررة: يسجل الجداول التشغيلية الأربعة والستين ويسلمها للعامل؛ قائد واحد في كل مرة
collab	دائمًا	WebSocket للتحرير التعاوني على `QUIRE_COLLAB_HTTP_PORT` (1234)
centrifugo	دائمًا	توزيع أحداث الوقت الحقيقي على `QUIRE_REALTIME_PORT` (8000)
proxy	دائمًا	Caddy، بوابة TLS على المنفذين 80 و443 (راجع «TLS»)
valkey	`cache`	الذاكرة المؤقتة وحدود المعدل
clamav	`scan`	فحص الملفات المرفوعة من البرمجيات الخبيثة
gotenberg	`preview`	معاينة مستندات Office بصيغة PDF وعرض الشهادات
imgproxy	`images`	تغيير حجم الصور وتحويلها
transcoder	`video`	صورة العامل مع ffmpeg ذي ترخيص LGPL فقط لإنتاج نسخ الفيديو
seaweedfs	`storage`	تخزين كائني متوافق مع S3 على هذا المضيف
otelcol	`observability`	مجمّع OpenTelemetry
mailpit	`devmail`	يلتقط كل البريد الصادر لتجربة Quire
backup	`backup`	نسخة أساسية لمرة واحدة؛ راجع backup-restore.md
backup-scheduler, backup-offsite	`backup`	نسخة أساسية كل `QUIRE_BACKUP_INTERVAL_HOURS` ونسخ مشفرة خارج المضيف مع تمرين تحقق أسبوعي
h5p	`h5p`	صورة أداة H5P LTI 1.3 التي توفرها عبر `QUIRE_H5P_IMAGE` على `QUIRE_H5P_PORT` (8090)؛ راجع «ربط موفر H5P»

يبدأ --profile full كل الخدمات الاختيارية عدا backup وh5p. ابدأ خدمة واحدة عبر docker compose -f docker/compose.yaml --profile scan up -d. ويواصل Quire العمل دون خدمة اختيارية ويوضح ما ينقص: من دون ماسح تُخزن الرفعات بلا فحص ويُخطر المسؤول؛ ومن دون Gotenberg يصبح تنزيل الملفات متاحًا بدل معاينتها؛ ومن دون محول فيديو يُشغل الملف الأصلي.

ترد كل صورة طرف ثالث والتزامات ترخيصها في docker/third-party-containers.yaml.

ربط موفر H5P

لا يضمّن Quire بيئة تشغيل H5P أو خدمة جانبية لها ولا يوفرهما (ADR 0019). إذا كنت تستخدم H5P، فاشترك في خدمة مستضافة خاصة بك أو شغّل نسخة H5P مستضافة ذاتيًا بصورة مستقلة عن Quire. سجّل الموفر كأداة LTI 1.3 خارجية وأضف محتواه إلى المقررات كنشاط أداة. يتبادل Quire الدرجات وتقدم النشاط والتصحيح عبر خدمات الواجبات والدرجات في LTI (AGS). وإذا أرسل الموفر عبارات xAPI أيضًا، فضبطها منفصلًا لمخزن عبارات xAPI في Quire؛ فتبادل درجات وتقدم AGS لا يرسل عبارات xAPI. وتوضح عمليات استيراد Moodle أن أنشطة H5P تحتاج إلى اتصال أداة LTI. ويبقى الموفر مسؤولًا عن بيئة H5P وتأليفه وبنك محتواه وسجل محاولاته.

لتشغيل نسختك المستضافة ذاتيًا على هذا المضيف، عيّن QUIRE_H5P_IMAGE على صورتها وابدأ ملف التعريف h5p. ينشرها Compose على QUIRE_H5P_PORT (8090) ويحفظ بياناتها في وحدة h5p-data؛ وتظل الصورة والتزاماتها مسؤوليتك.

الإعدادات

تقرأ كل عملية ملف docker/.env. ويسرد القالب docker/.env.example كل إعداد وقيمته الافتراضية. والمجموعات هي:

العناوين

الإعداد	المعنى
`QUIRE_APP_ORIGIN`	العنوان العام لنظام إدارة التعلم، مثل `https://learn.example.com`
`QUIRE_CONTENT_ORIGIN`	أصل المحتوى على مضيف مختلف
`QUIRE_PLATFORM_DOMAINS`	النطاقات التي تقع ضمنها المؤسسات، مفصولة بفواصل
`QUIRE_MARKETING_ORIGIN`	Optional. The marketing site, default `https://quirelms.com`. The only origin the waitlist form (`POST /api/waitlist`, `POST /waitlist`) accepts and redirects to. Comma separated; a `www.` variant is allowed only if listed
`QUIRE_DEPLOY_TARGET`	`compose` هنا. راجع الأدلة الأخرى لـ`vercel` و`cloudflare`
`QUIRE_TRUSTED_PROXY_CIDRS`	الوكلاء الذين نثق بقيمة `X-Forwarded-For` الواردة منهم

الأسرار

الإعداد	المعنى
`QUIRE_SECRET_KEY`	يوقع الجلسات والرموز. 64 حرفًا سداسيًا عشريًا
`QUIRE_MASTER_KEY`	يغلف بيانات الاعتماد المحفوظة مثل أسرار SSO وخطافات الويب. 32 بايت بترميز base64. يجب أن تستخدم طبقة الويب والعامل القيمة نفسها. التدوير: key-rotation.md
`QUIRE_MASTER_KEY_VERSION`	وسم إصدار المفتاح الرئيسي؛ `v1` عند عدم التحديد. ارفعه عند التدوير
`QUIRE_MASTER_KEY_RETIRED`	المفاتيح الرئيسية السابقة اللازمة لقراءة ما غلفته، مثل `v1=<base64>`. أزلها بعد اكتمال التدوير بلا قيم غير محسومة
`QUIRE_COLLAB_SIGNING_KEY`	مشترك بين web وcollab لتوقيع رموز التحرير
`QUIRE_BACKUP_SIGNING_KEY`	يوقع نسخ المقررات الاحتياطية (اختياري)

احتفظ بنسخة من QUIRE_MASTER_KEY خارج هذا المضيف. لا تستطيع قاعدة مستعادة فك تشفير بيانات الاعتماد دونها.

قاعدة البيانات

الإعداد	المعنى
`POSTGRES_PASSWORD`	كلمة مرور المستخدم الفائق، تستخدمها الحاوية والنسخ الاحتياطية
`QUIRE_DB_APP_PASSWORD` و`QUIRE_DB_MIGRATOR_PASSWORD` و`QUIRE_DB_REPORT_PASSWORD` و`QUIRE_DB_AUDIT_PASSWORD`	كلمات مرور الأدوار، تضبط عند أول تشغيل
`DATABASE_URL`	دور التطبيق؛ يطبق أمان الصفوف على كل استعلام ينفذه
`DATABASE_MIGRATOR_URL` و`QUIRE_MIGRATION_URL`	دور الترحيل لخدمتي `migrate` و`init`
`QUIRE_SUPERUSER_URL`	يستخدم في الإعداد الأول فقط
`QUIRE_REPORT_DATABASE_URL`	دور التقارير للقراءة فقط، يستخدمه مولد التقارير والتقارير
`QUIRE_AUDIT_DATABASE_URL`	دور التدقيق لوحدة التدقيق وتصدير SIEM
`QUIRE_DATABASE_ID`	أي UUID ثابت طوال عمر التثبيت

لا تطبق كلمات مرور الأدوار إلا عند إنشاء وحدة قاعدة البيانات أول مرة. لتغييرها لاحقًا، استخدم ALTER ROLE ثم حدّث عنوان URL المطابق.

يُستخدم QUIRE_REPORT_DATABASE_URL لقاعدة البيانات الفعلية المضبوطة في DATABASE_URL. ولكل قاعدة أخرى مسجلة، عيّن عنوان اتصالها الخاص بـquire_report في بيئتي الويب والعامل، ثم ضع اسم المتغير في حقل Reporting environment variable لتلك القاعدة بصيغة env:NAME. يجب أن يشير العنوان إلى قاعدة البيانات نفسها التي يشير إليها اتصال التطبيق، ويفضل إلى نسخة القراءة التابعة لها. تتبع كل واجهات التقارير المستأجر إلى اتصال التقارير الخاص بقاعدته: مولد التقارير والتقارير المحفوظة والتسليمات المجدولة وصادرات التقارير والتحليلات وسجل التدقيق وموارد تدقيق REST وبحث المساعد في التدقيق. ولا تستخدم أي منها عنوان تقارير خاصًا بقاعدة أخرى. إذا لم يكن لقاعدة ما اتصال تقارير، تُشغل التقارير العادية على اتصال التطبيق الخاص بها، بينما تُرفض التحليلات وكل عمليات قراءة التدقيق وتوضح السبب، لأن دور التطبيق لا يستطيع قراءة سجل التدقيق.

برامج التشغيل

الإعداد	الخيارات في هذا الإصدار	ملاحظات
`QUIRE_STORAGE_DRIVER`	`local` (افتراضي) أو `s3` أو `azure`	يحفظ `local` الملفات في وحدة `files`. ويدعم `s3` AWS S3 وR2 وتوافق GCS وغيرها من المخازن المتوافقة مع S3، مع رفع متعدد الأجزاء قابل للاستئناف
`QUIRE_REALTIME_DRIVER`	`inprocess` (افتراضي) أو `sse` أو `centrifugo` أو `durable_objects`	يناسب `inprocess` حاوية ويب واحدة؛ استخدم `centrifugo` أو `sse` عند وجود عدة حاويات
`QUIRE_CACHE_DRIVER`	`memory` (افتراضي) أو `postgres` أو `valkey`	ذاكرة `memory` خاصة بكل عملية؛ استخدم `valkey` أو `postgres` لتطبيق حدود المعدل عبر الحاويات
`QUIRE_VIDEO_DRIVER`	`ffmpeg` (افتراضي) أو `progressive_mp4`	أو استخدم موفرًا مستضافًا مثل Cloudflare Stream أو Mux أو Bunny عبر مفاتيحه
`QUIRE_IMAGE_DRIVER`	`noop` (افتراضي) أو `imgproxy` أو `cloudflare`	يعرض `noop` كل صورة بحجمها الأصلي. يتطلب `imgproxy` ملف التعريف `images` والإعدادات أدناه؛ ويستخدم `cloudflare` خدمة Cloudflare Images
`QUIRE_MEETING_PROVIDER`	`bbb` أو `zoom` أو `teams` أو `meet` أو `jitsi` أو `in_process`	الموفر الافتراضي للجلسات المباشرة. إذا لم يُضبط، توضح الجلسات أنها غير معدة إلى أن تربط المؤسسة حسابها من التكاملات وإعداد موفر الجلسات. يتقدم حساب المؤسسة الخاص دائمًا على هذه القيمة. تُقرأ إعدادات الموفر المحدد فقط (`BBB_URL` و`BBB_SECRET` ومتغيرات `ZOOM_` و`TEAMS_` و`GOOGLE_MEET_` و`JITSI_`)
`QUIRE_MEETING_REGIONS`	قائمة مفصولة بفواصل من `eu` و`uk` و`us`	المناطق التي يعالج فيها الموفر الافتراضي للمنصة الاجتماعات. وإذا لم تُضبط، فلن تجري مقارنة المنطقة بمؤسسة مقيدة، كما في السابق. تحدد المؤسسة مناطق حسابها الخاص في صفحته

يرفض بدء طبقة الويب قيمة برنامج تشغيل غير مدعومة في هذا الإصدار ويسمي الإعداد بدل استبداله بالقيمة الافتراضية بصمت.

الصور

تطلب الصفحات الصور بأربعة أحجام ثابتة عبر /api/files/{id}/image/{size}، الذي يتحقق من صلاحية الوصول نفسها إلى الملف ثم يحول الطلب إلى خدمة الصور. يمكن لكل مؤسسة طلب QUIRE_IMAGE_SPECS_PER_HOUR (افتراضيًا 2000) زوجًا جديدًا من الصور والأحجام في الساعة؛ ولا تحتسب الأحجام التي أُنتجت في تلك الساعة مسبقًا. استخدم valkey أو postgres لقيمة QUIRE_CACHE_DRIVER عند تشغيل أكثر من حاوية ويب لتطبيق الحد عليها جميعًا.

الإعداد	برنامج التشغيل	ملاحظات
`IMGPROXY_URL`	`imgproxy`	العنوان الذي تصل منه المتصفحات إلى imgproxy، مثل `https://images.example.org`. ينشر ملف التعريف `images` الخدمة على `QUIRE_IMAGES_PORT` (8082)
`IMGPROXY_KEY` و`IMGPROXY_SALT`	`imgproxy`	سلاسل سداسية عشرية، بالقيم نفسها التي يبدأ بها imgproxy. أنشئ كلًا منها عبر `openssl rand -hex 32`. يوقع Quire كل عنوان صورة بهما، فلا يعرض imgproxy صورًا لم يطلبها Quire
`QUIRE_IMAGE_SOURCE_ORIGIN`	`imgproxy` مع التخزين المحلي	مصدر الصور الأصلية الذي يجلب منه imgproxy. يضبط Compose القيمة `http://web:3000`. مع تخزين `s3` أو `azure` يجلب imgproxy من الحاوية ولا يستخدم هذا الإعداد
`CLOUDFLARE_ACCOUNT_ID` و`CLOUDFLARE_IMAGES_TOKEN` و`CLOUDFLARE_IMAGES_ACCOUNT_HASH`	`cloudflare`	رمز API بإذن تعديل Images وتجزئة الحساب من Images ضمن Developer resources. فعّل المتغيرات المرنة للحساب
`CLOUDFLARE_IMAGES_SIGNING_KEY`	`cloudflare`	اختياري. عند ضبطه تكون الصور خاصة وكل عنوان موقعًا وينتهي بعد مدة. وبدونه تكون الصور عامة بعناوين مشتقة من `QUIRE_SECRET_KEY` لا يمكن لأحد تخمينها

تحتفظ Cloudflare Images بنسختها الخاصة من كل أصل تعرضه. وعند حذف ملف، يحذف العامل تلك النسخة قبل الأصل.

قائمة المهام

تستخدم المهام الخلفية pg-boss في قاعدة Postgres نفسها، فلا يلزم تشغيل خدمة قائمة انتظار أو إعدادها. وتُضاف المهمة ضمن المعاملة نفسها التي أحدثتها، كي لا يؤدي التعطل إلى فقدانها أو إرسالها مرتين. برنامج التشغيل QUIRE_QUEUE_DRIVER هنا هو pgboss افتراضيًا؛ وتنقل vercel وcloudflare تسليمات الإشعارات وخطافات الويب الخفيفة فقط إلى قائمة المنصة، وتشرح أدلة Vercel وCloudflare ذلك وكيفية إدراج طبقات الويب للمهام.

البريد الإلكتروني

اختر أحد الإعدادين:

QUIRE_EMAIL_PROVIDER_CONFIG: كائن JSON يحدد موفر HTTP وبيانات اعتماده، مثل {"provider":"postmark","token":"..."}. تتوفر Postmark وAmazon SES وMailgun وSendGrid وResend.
QUIRE_SMTP_URL: مثل smtp://user:password@host:587. يقتصر ذلك على هذه البيئة؛ فبيئات serverless تمنع SMTP.

القيمة QUIRE_MAIL_FROM هي المرسل. ولتجربة Quire، ابدأ ملف التعريف devmail واضبط QUIRE_SMTP_URL=smtp://mailpit:1025 واقرأ البريد في http://localhost:8025.

خدمات اختيارية

الإعداد	ملف التعريف
`CLAMAV_URL=tcp://clamav:3310`	`scan`
`GOTENBERG_URL=http://gotenberg:3000`	`preview`
`IMGPROXY_KEY` و`IMGPROXY_SALT`	`images`
`VALKEY_URL=redis://valkey:6379`	`cache`
`QUIRE_OPENSEARCH_URL` أو `QUIRE_MEILISEARCH_URL`	البحث الخارجي؛ وإلا يستخدم بحث Postgres بالنص الكامل
`QUIRE_BREACH_CHECK_PROVIDER=off` و`QUIRE_BREACH_CHECK_URL`	فحص كلمات المرور المسربة. يعمل افتراضيًا عبر `api.pwnedpasswords.com` (لا يُرسل سوى بادئة تجزئة من خمسة أحرف)؛ تعطل القيمة `off` الفحص ويشير العنوان إلى API نطاقات تستضيفه بنفسك

الرصد

يحدد OTEL_EXPORTER_OTLP_ENDPOINT عنوان المجمّع الذي ترسل إليه كل عملية آثارها ومقاييسها. وفي ملف التعريف observability تكون قيمته http://otelcol:4318، ويمكنك إضافة موفر نظامك في docker/otel-collector.yaml. تصدر طبقة الويب والعامل والمجدول والمحتوى وcollab امتدادات عبر OTLP/HTTP (طلبات الويب ومعاملات قاعدة بيانات المستأجر ومهام العامل والاتصالات الصادرة) عند ضبطه، وترسل المقاييس إلى العنوان نفسه كل دقيقة (OTEL_METRICS_EXPORTER=none يعطلها). يحدد OTEL_TRACES_SAMPLER_ARG نسبة الآثار المحتفظ بها. وتُرسل السجلات إلى الإخراج القياسي وفق LOG_LEVEL ويتولى Compose تدويرها. ولا تحمل الآثار بيانات شخصية مطلقًا.

الخروج الإقليمي (إقامة بيانات الاتحاد الأوروبي)

تعني QUIRE_REGION=eu أن الحزمة تخدم مؤسسات الاتحاد الأوروبي. عندها يقصر العامل كل طلب صادر لمؤسسة مقيدة بالاتحاد الأوروبي على قائمة سماح (21-compliance.md القسم 8.1). تضم القائمة مضيفي الخدمات المضبوطة للمنطقة (نقطة التخزين وموفر البريد والفيديو المستضاف وأهداف تخزين المؤسسة وموفري الذكاء الاصطناعي وحساب البريد)، ومضيفي أي خدمة يشملها استثناء نشط، والمضيفين المدرجين في QUIRE_EGRESS_ALLOW_HOSTS. ويُرفض أي طلب إلى مضيف عام آخر قبل إرساله، ويسجل الرفض في سجل تدقيق المؤسسة باسم privacy/egress_refused ويظهر ضمن الامتثال وإقامة البيانات.

الإعداد	القيم	الأثر
`QUIRE_EGRESS_ALLOW_HOSTS`	قائمة مضيفين مفصولة بفواصل أو `*.example.org` لكل نطاق فرعي	مضيفون إضافيون يمكن لمؤسسة أوروبية الوصول إليهم. أضف نقاط نهاية خطافات الويب وxAPI وSIEM وموجزات المدونات ومضيفي Amazon SES لأنها خيارات خاصة بالمؤسسة ولا يعلن عنها موفر خدمة. ولا يجري فحص عناوين loopback والعناوين الخاصة والأسماء ذات المقطع الواحد مثل `web` أو `clamav` لأنها شبكتك الخاصة

لا تُقيد المؤسسات البريطانية والأمريكية بقائمة مضيفين، بل تظل خاضعة لفحوص منطقة الخدمة. عيّن القائمة للعامل؛ وتقرأها صفحة الإدارة من طبقة الويب لعرضها، لذا ضعها في docker/.env الذي تقرؤه الخدمات كلها.

يعرض فحص التطبيق خطأ واضحًا وإدخالًا في سجل التدقيق، لكنه ليس الضمان لأن الشيفرة قد تخطئ؛ الضمان على مستوى الشبكة. لا يفرض Compose ذلك عنك. للحزمة الإقليمية، ضع خدمتي worker وweb في شبكة internal: true لا يخرج منها سوى وكيل خروج (مثل حاوية Squid أو tinyproxy) يسمح بالمضيفين أنفسهم في QUIRE_EGRESS_ALLOW_HOSTS وبمضيفي الخدمات المضبوطة، واضبط HTTPS_PROXY لتلك الخدمات. تسرد صفحة إقامة البيانات المضيفين الذين يسمح بهم التطبيق لتتمكن من مقارنة القائمتين.

الصحة

نقطة النهاية	المعنى
`/healthz`	الحيوية: العملية تستجيب. تستخدمها فحوص Compose الصحية
`/readyz`	الجاهزية: يمكن الوصول إلى التبعيات، ويُذكر ما إذا كانت كل خدمة اختيارية مضبوطة. وجّه موازن التحميل إليها

يعرض docker compose -f docker/compose.yaml ps حالة صحة كل خدمة.

TLS

تُعد خدمة proxy (Caddy بترخيص Apache-2.0 من docker/caddy/Caddyfile) جزءًا من الحزمة الافتراضية. تستمع على المنفذين 80 و443 وتوجه الطلبات كما يلي:

المضيف أو المسار	الوجهة
`QUIRE_PROXY_CONTENT_HOST`	`content`
`QUIRE_PROXY_APP_HOST` وكل نطاق مستأجر فرعي ونطاق مخصص	`web`
`/_collab/` على تلك المضيفات	`collab` (WebSocket، عبر `QUIRE_COLLAB_URL`)
`/_realtime/connection/` على تلك المضيفات	WebSocket عميل `centrifugo`؛ ولا تُكشف واجهة API الخاصة بخادمه مطلقًا
`/_images/` على تلك المضيفات	`imgproxy` مع ملف التعريف `images` (`IMGPROXY_URL`)

يستنتج init-env.sh الإعدادات QUIRE_PROXY_APP_HOST وQUIRE_PROXY_CONTENT_HOST وQUIRE_PROXY_HTTPS_PORT وQUIRE_COLLAB_URL وIMGPROXY_URL من الأصلين كي لا تتعارض. غيّرها معًا إذا غيرت أحد العنوانين يدويًا.

تتبع الشهادات القيمة QUIRE_PROXY_TLS:

internal (الافتراضي): سلطة الشهادات الخاصة بـCaddy لـlocalhost و*.localhost وlvh.me. ثق بجذرها مرة واحدة ثم افتح المتصفح:
```
docker compose -f docker/compose.yaml cp \
  proxy:/data/caddy/pki/authorities/local/root.crt ./quire-local-ca.crt
```
أضف quire-local-ca.crt إلى مخزن الثقة في النظام أو المتصفح. مررها إلى curl باستخدام --cacert.
عنوان بريد إلكتروني: شهادات ACME تلقائية (Let’s Encrypt ثم ZeroSSL) للمضيفات الحقيقية. يجب أن يشير DNS للأصلين وكل مضيف مستأجر إلى هذا المضيف، وأن يكون المنفذان 80 و443 متاحين من الإنترنت.

تصدر شهادات المضيفين المستأجرين عند الطلب في أول زيارة، وفقط بعد أن تؤكد web أن الاسم تابع لهذا التثبيت (/tls-allowed على شبكة Compose). لا تحتاج إلى شهادة بدل wildcard أو إضافة لموفر DNS، ولا يستطيع غريب يشير بنطاقه إلى المضيف جعله يطلب شهادة. تحفظ الشهادات والسلطة المحلية في وحدة caddy-data؛ احتفظ بنسخة منها مع بقية النسخ الاحتياطية عند استخدام internal.

تثق web بقيمة X-Forwarded-For من الوكيل فقط: للوكيل عنوان ثابت (QUIRE_PROXY_ADDRESS، الافتراضي 172.29.64.10) على شبكة فرعية ثابتة (QUIRE_COMPOSE_SUBNET)، ويحدد QUIRE_TRUSTED_PROXY_CIDRS ذلك العنوان. إذا تعارضت الشبكة الفرعية مع شبكة على المضيف، غيّر القيمتين ونفذ docker compose down قبل up.

خلف وكيل عكسي خاص بك

لاستخدام موازن تحميل أو وكيل تشغله مسبقًا، استبعد خدمة proxy (docker compose up -d --scale proxy=0) وأنهِ TLS أمام web (8080) وcontent (8081) وcollab (1234، WebSocket) وcentrifugo (8000، WebSocket). عيّن العناوين العامة في QUIRE_APP_ORIGIN وQUIRE_CONTENT_ORIGIN وQUIRE_COLLAB_URL (مع wss://)، ونطاق عناوين وكيلك في QUIRE_TRUSTED_PROXY_CIDRS.

استكشاف المشكلات

خروج init مع الرسالة «QUIRE_DATABASE_ID is not a UUID»: عيّن القيمة باستخدام uuidgen.
إعادة تشغيل web مع الرسالة «did not start on compose»: يسرد السجل الإعدادات التي لا يمكن احترامها والبدائل المطلوبة.
تغيير كلمة مرور دور في .env بعد أول تشغيل لا يفعل شيئًا: يعمل نص الإعداد مرة واحدة. استخدم ALTER ROLE.
فشل الرفع بسبب خطأ فحص مع ضبط CLAMAV_URL: ينزل ClamAV التواقيع عند أول تشغيل وقد يستغرق ذلك بضع دقائق.