نصب Quire با Docker Compose

این محصول کامل روی یک میزبان است: LMS، کارهای پس‌زمینه‌اش، سرویس‌های بلادرنگ و ویرایش گروهی و همهٔ سرویس‌های اختیاری پشت یک profile. طرح در بخش ۲ از docs/architecture/23-ops.md آمده است.

مقصدهای دیگر: Vercel و Cloudflare Workers فقط web tier را اجرا می‌کنند. ارتقاها در upgrade.md و پشتیبان‌گیری و تمرین بازیابی در backup-restore.md آمده‌اند.

چیزهای لازم

• Docker Engine نسخهٔ ۲۷ یا بالاتر و افزونهٔ Compose نسخهٔ ۲٫۳۰ یا بالاتر.
• برای stack پیش‌فرض ۴ هستهٔ CPU و ۸ GB حافظه؛ با --profile full هشت هسته و ۱۶ GB (ClamAV به‌تنهایی حدود ۱٫۵ GB امضای ویروس نگه می‌دارد).
• یک نام DNS برای web tier و نامی دیگر برای محتوای غیرقابل‌اعتماد. باید میزبان‌های متفاوتی باشند: بسته‌های SCORM و HTML بارگذاری‌شده روی origin محتوا اجرا می‌شوند تا هرگز نتوانند کوکی‌های LMS را بخوانند.
• برای آزمون محلی، lvh.me و *.localhost به 127.0.0.1 اشاره می‌کنند و docker/.env.example هم همین را به کار می‌برد. سرویس proxy خود stack هر دو را با https و مرجع گواهی محلی ارائه می‌کند؛ پس چیز دیگری نصب نمی‌شود (بخش «TLS» را ببینید).
• پورت‌های ۸۰ و ۴۴۳ روی میزبان آزاد باشند (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 می‌سازد (گذرواژه‌های پایگاه داده، کلیدهای امضا و اصلی و جفت‌کلید راه‌اندازی محتوا) و کلید امضای checkpoint حسابرسی را در docker/secrets/audit-signing-key.pem می‌گذارد که Compose آن را به‌صورت secret در workerها mount می‌کند. فقط sh، awk و openssl لازم دارد و نمی‌گذارد docker/.env موجود بازنویسی شود. هر دو فایل را از میزبان بیرون کپی کنید: بدون QUIRE_MASTER_KEY پایگاه بازیابی‌شده نمی‌تواند اعتبارنامه‌های ذخیره‌شده را رمزگشایی کند. برای پر کردن دستی فایل، cp docker/.env.example docker/.env را اجرا کنید؛ فایل شیوهٔ ساخت هر راز را می‌گوید.

هر دو origin باید https باشند: سرویس content در محیط عملیاتی http ساده را رد می‌کند و دو origin نباید دامنهٔ ثبت‌پذیر مشترک داشته باشند. سرویس proxy برای هر دو TLS را پایان می‌دهد (بخش «TLS» را ببینید)؛ init-env.sh originای با http:// را رد می‌کند.

Stack با ترتیب ثابتی آغاز می‌شود و هر گام برای پایان قبلی منتظر می‌ماند:

1. postgres سالم می‌شود. در نخستین راه‌اندازی، اسکریپت آغازش (docker/postgres/init/90-passwords.sh) گذرواژهٔ چهار نقش را تنظیم می‌کند.
2. migrate همهٔ migrationها را اجرا و صف job را در پایگاه کنترل و هر پایگاه tenant اختصاصی آماده می‌کند؛ بررسی می‌کند همگی یکسان باشند و سپس خارج می‌شود (docs/ops/upgrade.md). Migration در هر آغاز اجرا می‌شوند و تکرارپذیرند، پس ارتقا یعنی image تازه و راه‌اندازی مجدد.
3. init (apps/web/src/first-run.ts) پایگاه برنامه را زیر شناسهٔ QUIRE_DATABASE_ID ثبت می‌کند و اگر QUIRE_SETUP_ADMIN_EMAIL تنظیم شده باشد نخستین سازمان و مدیرش را می‌سازد. نشانی ورود و گذرواژهٔ تولیدشده فقط یک‌بار در docker compose logs init چاپ می‌شوند.
4. web، content، worker، scheduler، collab و centrifugo آغاز می‌شوند.
5. proxy پس از سالم شدن web و content آغاز می‌شود.

https://demo. را به دامنهٔ برنامه‌تان بچسبانید و آن نشانی را باز کنید؛ گزارش init نشانی دقیق ورود را چاپ می‌کند. در نصب محلی ابتدا مرجع گواهی proxy را معتبر بدانید (بخش «TLS» را ببینید). گذرواژهٔ تولیدشده را در /account/security عوض کنید.

فرایندی که بدون راز لازم آغاز شود، از کار سر باز می‌زند و تنظیم گمشده را در گزارش نام می‌برد. هیچ‌چیز نیمه‌پیکربندی‌شده آغاز نمی‌شود.

سرویس‌ها و profileها

--profile full همهٔ سرویس‌های اختیاری جز backup و h5p را آغاز می‌کند. برای نمونه docker compose -f docker/compose.yaml --profile scan up -d را اجرا کنید. Quire بدون سرویس اختیاری هم کار می‌کند و کمبود را می‌گوید: اگر scanner نباشد، بارگذاری‌ها بدون scan ذخیره می‌شوند و مدیر باخبر می‌شود؛ اگر Gotenberg نباشد، فایل‌ها به‌جای پیش‌نمایش امکان بارگیری می‌دهند؛ اگر transcoder نباشد، ویدیو به‌صورت فایل اصلی پخش می‌شود.

همهٔ imageهای شخص ثالث و تعهدهای مجوزشان در docker/third-party-containers.yaml فهرست شده‌اند.

اتصال ارائه‌دهندهٔ H5P

Quire زمان‌اجرای H5P را در خود جاسازی یا همراه محصول عرضه نمی‌کند و sidecar هم ندارد (ADR 0019). اگر H5P به کار می‌برید، اشتراک میزبانی‌شدهٔ خودتان را فراهم کنید یا نمونهٔ H5P خودمیزبانی را جدا از Quire اداره کنید. ارائه‌دهنده را به‌شکل ابزار بیرونی LTI 1.3 ثبت کنید و محتوایش را به‌صورت فعالیت ابزار به دوره‌ها بیفزایید. Quire نمره‌ها و پیشرفت فعالیت و نمره‌دهی را از راه LTI Assignment and Grade Services (AGS) ردوبدل می‌کند. اگر ارائه‌دهنده xAPI statement هم می‌فرستد، آن را جداگانه برای مخزن xAPI statement در Quire پیکربندی کنید؛ مبادلهٔ نمره و پیشرفت AGS، xAPI statement نمی‌فرستد. ورودهای Moodle گزارش می‌دهند که فعالیت H5P به اتصال ابزار LTI نیاز دارد. زمان‌اجرا، ساخت محتوا، بانک محتوا و تاریخچهٔ تلاش‌های H5P در مسئولیت ارائه‌دهنده می‌مانند.

برای اجرای نمونهٔ خودمیزبانی در این میزبان، QUIRE_H5P_IMAGE را روی image آن بگذارید و profile h5p را آغاز کنید. Compose آن را روی QUIRE_H5P_PORT (8090) منتشر می‌کند و داده‌هایش را در volume h5p-data نگه می‌دارد؛ image و تعهدهای همراهش از آنِ شما می‌مانند.

تنظیم‌ها

هر فرایند docker/.env را می‌خواند. الگوی docker/.env.example همهٔ تنظیم‌ها و مقدارهای پیش‌فرضشان را فهرست می‌کند. گروه‌ها:

نشانی‌ها

رازها

از QUIRE_MASTER_KEY نسخه‌ای جایی بیرون از این میزبان نگه دارید. اگر پایگاه داده بدون آن بازیابی شود، اعتبارنامه‌های داخلش رمزگشایی نمی‌شوند.

پایگاه داده

گذرواژهٔ نقش‌ها فقط هنگام نخستین ساخت volume پایگاه داده اعمال می‌شوند. برای تغییر بعدی، ALTER ROLE را اجرا و URL متناظر را به‌روز کنید.

QUIRE_REPORT_DATABASE_URL برای پایگاه فیزیکی‌ای است که با DATABASE_URL تنظیم شده است. برای هر پایگاه فیزیکی ثبت‌شدهٔ دیگر، URL اتصال quire_report خودش را در محیط‌های web و worker تنظیم کنید و سپس نام متغیر را در فیلد Reporting environment variable آن پایگاه به‌شکل env:NAME بگذارید. ارجاع باید به همان پایگاهی برود که اتصال برنامه می‌رود، بهتر آنکه read replicaاش باشد. هر سطح گزارش با tenant به اتصال گزارش همان پایگاه می‌رود: سازنده و گزارش‌های ذخیره‌شده، تحویل‌های زمان‌بندی‌شده، خروجی گزارش، analytics، گزارش حسابرسی، منبع‌های حسابرسی REST و جست‌وجوی حسابرسی دستیار. هیچ‌کدام از URL گزارش پایگاه دیگری قرض نمی‌گیرند. اگر پایگاهی اتصال گزارش نداشته باشد، گزارش‌های عادی از اتصال برنامهٔ همان پایگاه اجرا می‌شوند؛ اما analytics و هر خواندن حسابرسی رد می‌شوند و علت را می‌گویند، چون نقش برنامه نمی‌تواند گزارش حسابرسی را بخواند.

Driverها

مقدار driverای که این نسخه ندارد هنگام آغاز web tier رد می‌شود و تنظیم را نام می‌برد؛ بی‌صدا با مقدار پیش‌فرض جایگزین نمی‌شود.

تصویرها

صفحه‌ها از راه /api/files/{id}/image/{size} در چهار اندازهٔ ثابت تصویر می‌خواهند؛ این endpoint دسترسی همان فایل را بررسی می‌کند و سپس به سرویس تصویر تغییرمسیر می‌دهد. هر سازمان می‌تواند در هر ساعت برای QUIRE_IMAGE_SPECS_PER_HOUR (پیش‌فرض ۲۰۰۰) جفت تازهٔ تصویر و اندازه درخواست کند؛ اندازه‌هایی که همان ساعت ساخته شده‌اند در شمار نمی‌آیند. اگر بیش از یک web container دارید، برای یکسان نگه داشتن سقف valkey یا postgres را برای QUIRE_CACHE_DRIVER برگزینید.

Cloudflare Images نسخه‌ای از هر تصویر اصلی را که ارائه می‌کند نگه می‌دارد. هنگام حذف فایل، worker آن نسخه را پیش از تصویر اصلی پاک می‌کند.

صف

کارهای پس‌زمینه از pg-boss در همان پایگاه Postgres استفاده می‌کنند، پس نه سرویس صفی لازم است اجرا کنید و نه چیزی پیکربندی کنید. jobها در همان transaction تغییرِ سبب‌ساز صف می‌شوند تا crash نتواند آن‌ها را گم کند یا دوبار بفرستد. اینجا QUIRE_QUEUE_DRIVER مقدار پیش‌فرض pgboss دارد؛ vercel و cloudflare فقط تحویل سبک اعلان و وب‌هوک را به صف خود پلتفرم می‌برند. راهنماهای Vercel و Cloudflare آن‌ها و شیوهٔ صف‌بندی web tier را توضیح می‌دهند.

ایمیل

یکی از این‌ها را تنظیم کنید:

• 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، profile devmail را آغاز، QUIRE_SMTP_URL=smtp://mailpit:1025 را تنظیم و ایمیل را در http://localhost:8025 بخوانید.

سرویس‌های اختیاری

مشاهده‌پذیری

OTEL_EXPORTER_OTLP_ENDPOINT نام گردآورنده‌ای را مشخص می‌کند که هر فرایند trace و metric به آن می‌فرستد؛ با profile observability مقدارش http://otelcol:4318 است و docker/otel-collector.yaml جایی است که exporter مربوط به backend خودتان را می‌افزایید. web tier، worker، scheduler، content و collab اگر این مقدار تنظیم شود spanها را از راه OTLP/HTTP می‌فرستند (درخواست‌های وب، transactionهای پایگاه tenant، jobهای worker و فراخوانی‌های خروجی) و هر دقیقه metric هم به همان endpoint می‌فرستند (OTEL_METRICS_EXPORTER=none آن‌ها را خاموش می‌کند). OTEL_TRACES_SAMPLER_ARG سهم traceهایی را که نگه داشته می‌شوند تعیین می‌کند. گزارش‌ها با LOG_LEVEL به خروجی استاندارد می‌روند و Compose آن‌ها را چرخش می‌دهد. traceها هرگز دادهٔ شخصی ندارند.

خروجی منطقه‌ای (اقامت داده در EU)

QUIRE_REGION=eu می‌گوید stack به سازمان‌های اتحادیهٔ اروپا خدمت می‌دهد. آن‌گاه worker هر درخواست خروجی‌ای را که برای سازمان سنجاق‌شده به EU انجام می‌شود به allowlist محدود می‌کند (21-compliance.md، بخش 8.1). allowlist شامل میزبان‌هایی است که سرویس‌های پیکربندی‌شده برای منطقه اعلام می‌کنند (نقطهٔ پایانی ذخیره‌سازی، ارائه‌دهندهٔ ایمیل، ارائه‌دهندهٔ ویدیوی میزبانی‌شده، مقصدهای ذخیره‌سازی خود سازمان، ارائه‌دهندگان هوش مصنوعی و حساب ایمیل)، میزبان‌های هر سرویسی زیر derogation فعال و میزبان‌هایی که در QUIRE_EGRESS_ALLOW_HOSTS می‌نویسید. درخواست به هر میزبان عمومی دیگر پیش از فرستادن رد می‌شود؛ ردشدن در گزارش حسابرسی سازمان با privacy/egress_refused نوشته و در Compliance، Data residency فهرست می‌شود.

سازمان‌های UK و US به فهرست میزبان محدود نیستند و بررسی منطقهٔ سرویس برایشان برقرار می‌ماند. فهرست را روی worker تنظیم کنید؛ صفحهٔ مدیریت برای نمایش allowlist آن را از web tier می‌خواند، پس در docker/.env بگذارید که همهٔ سرویس‌ها می‌خوانند.

بررسی برنامه خطا و ورودی حسابرسی روشنی می‌دهد، اما تضمین نیست: کد ممکن است اشتباه کند. تضمین را شبکه فراهم می‌کند. Compose خودش آن را اجرا نمی‌کند. برای stack منطقه‌ای، سرویس‌های worker و web را در شبکهٔ internal: true بگذارید که تنها مسیر خروجش egress proxy باشد (برای نمونه container مربوط به Squid یا tinyproxy)؛ proxy باید همان میزبان‌های QUIRE_EGRESS_ALLOW_HOSTS و میزبان سرویس‌های پیکربندی‌شده را مجاز کند و برای سرویس‌ها HTTPS_PROXY بگذارید. صفحهٔ اقامت داده میزبان‌هایی را که برنامه مجاز می‌داند دقیقاً فهرست می‌کند تا دو فهرست را مقایسه کنید.

سلامت

docker compose -f docker/compose.yaml ps سلامت هر سرویس را نشان می‌دهد.

TLS

سرویس proxy (Caddy، Apache-2.0، docker/caddy/Caddyfile) بخشی از stack پیش‌فرض است. به پورت‌های ۸۰ و ۴۴۳ پاسخ می‌دهد و چنین مسیریابی می‌کند:

init-env.sh از دو origin، QUIRE_PROXY_APP_HOST، QUIRE_PROXY_CONTENT_HOST، QUIRE_PROXY_HTTPS_PORT، QUIRE_COLLAB_URL و IMGPROXY_URL را به‌دست می‌آورد تا از هم دور نشوند. اگر originای را دستی تغییر می‌دهید، همه را با هم ویرایش کنید.

گواهی‌ها تابع 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) برای hostnameهای واقعی. DNS هر دو origin و هر میزبان tenant باید به اینجا برسد و پورت‌های ۸۰ و ۴۴۳ از اینترنت در دسترس باشند.

گواهی میزبان tenant هنگام نخستین بازدید و فقط وقتی صادر می‌شود که web تأیید کند نام به همین نصب تعلق دارد (/tls-allowed که در شبکهٔ Compose پرسیده می‌شود). گواهی wildcard یا افزونهٔ DNS provider لازم نیست و غریبه‌ای که نامی را به میزبان اشاره دهد نمی‌تواند باعث درخواست گواهی شود. گواهی‌ها و مرجع محلی در volume caddy-data هستند؛ اگر از internal استفاده می‌کنید همراه بقیه پشتیبان بگیرید.

Web فقط X-Forwarded-For را از proxy باور می‌کند: proxy نشانی ثابت (QUIRE_PROXY_ADDRESS، پیش‌فرض 172.29.64.10) در subnet ثابتی (QUIRE_COMPOSE_SUBNET) دارد و QUIRE_TRUSTED_PROXY_CIDRS همان نشانی را مشخص می‌کند. اگر subnet با شبکه‌ای در میزبان تداخل داشت، هر دو را عوض کنید، ابتدا docker compose down را اجرا کنید و پس از آن up را.

پشت reverse proxy خودتان

برای استفاده از load balancer یا proxyای که از پیش اجرا می‌کنید، 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://) و بازهٔ نشانی proxy را در 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 در نخستین آغاز امضاها را بارگیری می‌کند و این کار چند دقیقه زمان می‌برد.