Усталяванне Quire з Docker Compose

Гэта поўны прадукт на адным хосце: LMS, фонавыя задачы, сэрвісы рэальнага часу і сумеснага рэдагавання, а таксама ўсе дадатковыя сэрвісы, уключаныя праз профілі. Архітэктура апісана ў раздзеле 2 docs/architecture/23-ops.md.

Іншыя варыянты: 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 запускаюцца з origin змесціва, таму не могуць прачытаць cookie LMS.
• Для лакальнай праверкі 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 падключае яго да worker як secret. Патрэбныя толькі sh, awk і openssl; скрыпт адмаўляецца перазапісваць існы docker/.env. Скапіруйце абодва файлы з хоста: без QUIRE_MASTER_KEY адноўленая база даных не зможа расшыфраваць захаваныя ўліковыя даныя. Каб запоўніць файл уручную, выканайце cp docker/.env.example docker/.env; у файле ёсць інструкцыі па стварэнні кожнага сакрэту.

Абодва origin павінны выкарыстоўваць https: сэрвіс змесціва забараняе звычайны http у вытворчасці, і яны не павінны дзяліць рэгіструемы дамен. Сэрвіс proxy завяршае TLS для абодвух (гл. «TLS»); init-env.sh адхіляе origin з http://.

Стэк запускаецца ў фіксаваным парадку, кожны этап чакае завяршэння папярэдняга:

1. postgres пераходзіць у стан гатоўнасці. Пры першым запуску яго скрыпт ініцыялізацыі (docker/postgres/init/90-passwords.sh) задае паролі чатырох роляў.
2. migrate запускае ўсе міграцыі і ініцыялізуе чаргу задач у кантрольнай базе даных і ў кожнай асобнай базе арганізацыі, правярае, што ўсе яны супадаюць, а затым завяршаецца (гл. docs/ops/upgrade.md). Міграцыі запускаюцца пры кожным старце і ідэмпатэнтныя, таму абнаўленне — гэта новы вобраз і перазапуск.
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 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, падпішыцеся на ўласны размешчаны сэрвіс або асобна ад Quire запусціце ўласны асобны сэрвіс H5P. Зарэгіструйце правайдара як знешні інструмент LTI 1.3 і дадавайце яго змесціва ў курсы як інструментальныя заданні. Quire абменьваецца адзнакамі і прагрэсам заданняў праз LTI Assignment and Grade Services (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_MASTER_KEY асобна ад гэтага хоста. Адноўленая без яго база даных не зможа расшыфраваць захаваныя ўліковыя даныя.

База даных

Паролі роляў прымяняюцца толькі пры першым стварэнні тома базы даных. Каб змяніць пароль пазней, выкарыстоўвайце ALTER ROLE і абнавіце адпаведны URL.

QUIRE_REPORT_DATABASE_URL выкарыстоўваецца для фізічнай базы даных, зададзенай у DATABASE_URL. Для любой іншай зарэгістраванай фізічнай базы задавайце яе ўласны URL злучэння quire_report у асяроддзі web і worker, а затым у полі Reporting environment variable гэтай базы ўкажыце назву зменнай у фармаце env:NAME. Спасылка павінна весці да той жа базы, што і злучэнне прыкладання, пажадана да яе рэплікі толькі для чытання. Кожная частка справаздач выкарыстоўвае злучэнне сваёй базы для справаздач: канструктар і захаваныя справаздачы, запланаваныя рассылкі, экспарт, аналітыка, журнал аўдыту, рэсурсы REST аўдыту і пошук аўдыту памочнікам. Ніводная з іх не выкарыстоўвае URL справаздач іншай базы. Калі злучэнне для справаздач не зададзена, звычайныя справаздачы працуюць праз уласнае злучэнне прыкладання гэтай базы, а аналітыка і чытанне аўдыту адмаўляюцца працаваць і паведамляюць пра гэта, бо роля прыкладання не можа чытаць журнал аўдыту.

Драйверы

Калі ў гэтым выпуску няма зададзенага значэння драйвера, вэб-узровень адмаўляецца запускацца і называе нала́ду, замест таго каб моўчкі падмяніць яе значэннем па змаўчанні.

Выявы

Старонкі запытваюць выявы ў чатырох фіксаваных памерах праз /api/files/{id}/image/{size}. Гэты маршрут правярае тыя ж правы доступу, што і для самога файла, а потым перанакіроўвае запыт у сэрвіс выяў. Кожная арганізацыя можа запытваць да QUIRE_IMAGE_SPECS_PER_HOUR (першапачаткова 2000) новых пар выява-памер за гадзіну; памеры, створаныя ў тую ж гадзіну, не залічваюцца. Калі вэб-кантэйнераў некалькі, выкарыстоўвайце valkey або postgres для QUIRE_CACHE_DRIVER, каб абмежаванне дзейнічала на ўсіх.

Cloudflare Images захоўвае ўласную копію кожнай зыходнай выявы. Пры выдаленні файла worker выдаляе гэтую копію перад зыходным файлам.

Чарга

Фонавыя задачы выкарыстоўваюць pg-boss у той жа базе Postgres, таму асобны сэрвіс чаргі не патрэбны і нічога наладжваць не трэба. Задачы дадаюцца ў чаргу ў той самай транзакцыі, што і змена, якая іх выклікала, таму збой не можа прывесці да страты або паўторнай адпраўкі задачы. Тут QUIRE_QUEUE_DRIVER мае стандартнае значэнне pgboss; vercel і cloudflare пераносяць толькі лёгкія дастаўкі апавяшчэнняў і webhook у чаргу самой платформы. У інструкцыях 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.

Неабавязковыя сэрвісы

Назіранне

OTEL_EXPORTER_OTLP_ENDPOINT задае калектар, куды кожны працэс адпраўляе traces і метрыкі; з профілем observability гэта http://otelcol:4318. Наладзьце экспарцёр сваёй сістэмы ў docker/otel-collector.yaml. Калі параметр зададзены, вэб-узровень, worker, scheduler, content і collab адпраўляюць спаны праз OTLP/HTTP (запыты web, транзакцыі базы арганізацый, задачы worker і выходныя выклікі), а кожную хвіліну — метрыкі на той жа адрас (OTEL_METRICS_EXPORTER=none выключае іх). OTEL_TRACES_SAMPLER_ARG задае долю traces, якія захоўваюцца. Журналы выводзяцца ў стандартны вывад з узроўнем LOG_LEVEL, а Compose ратуе іх. Traces не змяшчаюць персанальных даных.

Рэгіянальны выходны трафік (рэзідэнцтва даных у ЕС)

QUIRE_REGION=eu азначае, што стэк абслугоўвае арганізацыі Еўрапейскага саюза. Worker абмяжоўвае выходныя запыты для арганізацыі, замацаванай за ЕС, спісам дазволеных вузлоў (раздзел 8.1 у 21-compliance.md). У спіс уваходзяць вузлы, абвешчаныя настроенымі сэрвісамі для гэтага рэгіёна (канчатковы адрас сховішча, правайдар пошты, размешчаны правайдар відэа, уласныя мэты сховішча арганізацыі, правайдары AI і ўліковы запіс пошты), вузлы сэрвісаў з актыўным адступленнем ад патрабаванняў, а таксама вузлы са спіса QUIRE_EGRESS_ALLOW_HOSTS. Запыт да любога іншага публічнага вузла адхіляецца да адпраўкі, адмова запісваецца ў журнал аўдыту арганізацыі як privacy/egress_refused і паказваецца ў раздзеле Compliance, Data residency.

Арганізацыі ў Вялікабрытаніі і ЗША не абмежаваныя спісам вузлоў; для іх захоўваюцца праверкі рэгіёна сэрвісаў. Задайце спіс у worker; старонка адміністратара чытае яго на вэб-узроўні, каб паказаць спіс дазволеных вузлоў, таму ўкажыце яго ў docker/.env, які чытаюць усе сэрвісы.

Праверка прыкладання выдае зразумелую памылку і запіс аўдыту, але не гарантуе абмежавання: у кодзе можа быць памылка. Гарантыю забяспечвае сетка. Compose не наладжвае яе за вас. Для рэгіянальнага стэка падключыце worker і web да сеткі internal: true, адзіны шлях з якой вонкі вядзе праз egress-проксі (напрыклад Squid або кантэйнер tinyproxy), наладжаную на тых жа вузлах, што і QUIRE_EGRESS_ALLOW_HOSTS, плюс вузлы настроеных сэрвісаў; задайце для гэтых сэрвісаў HTTPS_PROXY. Старонка рэзідэнцтва паказвае дакладныя вузлы, дазволеныя прыкладаннем, каб іх можна было параўнаць са спісам проксі.

Стан сэрвісаў

docker compose -f docker/compose.yaml ps паказвае стан кожнага сэрвісу.

TLS

Сэрвіс proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) уваходзіць у стандартны стэк. Ён слухае парты 80 і 443 і накіроўвае запыты:

init-env.sh выводзіць QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL і IMGPROXY_URL з двух origin, каб іх значэнні не разыходзіліся. Калі змяняеце 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) для сапраўдных хостаў. DNS абодвух origin і кожнага хоста арганізацыі павінен указваць сюды, а парты 80 і 443 павінны быць даступныя з інтэрнэту.

Сертыфікаты для хостаў арганізацый выдаюцца пры першым наведванні і толькі пасля таго, як web пацвердзіць, што імя належыць гэтай усталёўцы (запыт /tls-allowed у сетцы Compose). Wildcard-сертыфікат або ўбудова правайдара DNS не патрэбныя; незнаёмы чалавек, які накіруе дамен на гэты хост, не зможа прымусіць сістэму запытаць сертыфікат. Сертыфікаты і лакальны цэнтр сертыфікацыі захоўваюцца ў томе caddy-data; калі вы карыстаецеся internal, уключыце яго ў рэзервовую копію.

Web давярае X-Forwarded-For, атрыманаму толькі ад proxy: у proxy фіксаваны адрас (QUIRE_PROXY_ADDRESS, па змаўчанні 172.29.64.10) у фіксаванай падсетцы (QUIRE_COMPOSE_SUBNET), а QUIRE_TRUSTED_PROXY_CIDRS задае гэты адрас. Калі падсетка супадае з сеткай хоста, змяніце абедзве налады і выканайце docker compose down перад up.

За ўласным reverse 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://), а дыяпазон адрасоў вашага проксі — у 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 спампоўвае подпісы, гэта займае некалькі хвілін.