Shigar da Quire da Docker Compose

Wannan shi ne cikakken samfurin a uwar garke ɗaya: tsarin LMS, ayyukan baya, hidimomin ainihin-lokaci da gyaran haɗin gwiwa, da kowane hidima na zaɓi a bayan profile. Tsarin yana cikin sashen 2 na docs/architecture/23-ops.md.

Sauran manufa: Vercel da Cloudflare Workers suna gudanar da sashen yanar gizo kawai. Ana bayani kan sabuntawa a upgrade.md, kuma ajiyar bayanai da atisayen maido a backup-restore.md.

Abin da ake buƙata

• Docker Engine 27 ko sama, tare da Compose plugin 2.30 ko sama.
• Cores 4 na CPU da ƙwaƙwalwar 8 GB ga tsarin tsoho; cores 8 da ƙwaƙwalwar 16 GB tare da --profile full (ClamAV shi kaɗai yana riƙe kusan 1.5 GB na sa hannun cuta).
• Sunan DNS ga sashen yanar gizo da wani na biyu ga abun ciki marar amana. Dole su zama hosts daban: kunshin SCORM da HTML da aka loda suna gudana daga asalin abun ciki domin kada su taɓa karanta kukis na LMS.
• Don gwajin gida, lvh.me da *.localhost suna warwarewa zuwa 127.0.0.1, kamar yadda docker/.env.example ke amfani da shi. Hidimar proxy ta tsarin tana samar da HTTPS ga duka tare da cibiyar takardar shaida ta gida, saboda haka babu abin girkawa dabam (duba “TLS”).
• Tashoshi 80 da 443 su kasance a buɗe a uwar garken (QUIRE_PROXY_HTTP_PORT da QUIRE_PROXY_HTTPS_PORT na iya sauya su).

Gudanarwa ta farko

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 yana rubuta docker/.env daga docker/.env.example da dukkan sirrika da aka ƙirƙira (kalmomin sirrin ma’ajiya, maɓallan sa hannu da babba, maɓallan abun ciki), da maɓallin sa hannun matakin tantancewa a docker/secrets/audit-signing-key.pem, wanda Compose ke haɗawa da masu aiki a matsayin sirri. Yana buƙatar sh, awk da openssl kawai, kuma yana ƙin rubuta kan docker/.env da ya riga ya wanzu. Kwafi fayilolin biyu zuwa wajen uwar garken: idan babu QUIRE_MASTER_KEY, ma’ajiya da aka dawo ba za ta iya warware shaidar shiga da aka adana ba. Don cika fayil ɗin da hannu, yi cp docker/.env.example docker/.env; fayil ɗin yana bayyana yadda ake ƙirƙirar kowane sirri.

Dole asalin adireshin biyu su zama https: hidimar abun ciki tana ƙin http mara tsaro a yanayin samarwa, kuma dole kada su kasance a ƙarƙashin yankin da za a iya rajista iri ɗaya. Hidimar proxy ce ke kare su da TLS (duba “TLS”); init-env.sh yana ƙin asalin http://.

Tsarin yana farawa bisa tsayayyen jeri, kuma kowane mataki yana jiran wanda ya gabace shi:

1. postgres yana nuna lafiya. A farawa na farko, rubutun saita shi (docker/postgres/init/90-passwords.sh) yana saita kalmomin sirri guda huɗu.
2. migrate yana aiwatar da duk ƙaura, sannan yana shirya jerin aiki a ma’ajiya ta sarrafawa da kowace ma’ajiya ta ƙungiya ta musamman; yana tabbatar sun yi daidai, daga nan ya fita (docs/ops/upgrade.md). Ana gudanar da ƙaura a kowane farawa kuma ba sa maimaita tasiri, saboda haka sabuntawa sabon hoto ne da sake farawa.
3. init (apps/web/src/first-run.ts) yana rajistar ma’ajiya ta manhaja a ƙarƙashin QUIRE_DATABASE_ID, kuma idan an saita QUIRE_SETUP_ADMIN_EMAIL, yana ƙirƙirar ƙungiya ta farko da mai gudanarwarta. Ana buga adireshin shiga da kalmar sirri da aka ƙirƙira sau ɗaya a docker compose logs init.
4. web, content, worker, scheduler, collab da centrifugo suna farawa.
5. proxy yana farawa idan web da content sun nuna lafiya.

Buɗe https://demo. tare da yankin manhajarka (log na init yana nuna ainihin adireshin shiga), sannan shiga. A girkar gida, fara amincewa da cibiyar takardar shaida ta proxy (duba “TLS”). Canza kalmar sirrin da aka ƙirƙira a /account/security.

Tsarin da aka fara ba tare da sirrin da ake buƙata ba yana ƙin farawa kuma ya ambaci saitin da ya ɓace a log. Babu abin da ke farawa da saituna rabin-girma.

Hidimomi da profiles

--profile full yana fara kowace hidima ta zaɓi sai backup da h5p. Fara ɗaya da docker compose -f docker/compose.yaml --profile scan up -d. Ba tare da hidimar zaɓi ba, Quire yana aiki kuma yana bayyana abin da babu: babu mai binciken malware yana nufin ana adana loda ba tare da dubawa ba kuma ana sanar da mai gudanarwa; babu Gotenberg yana sa fayiloli su bayar da saukewa maimakon samfoti; babu mai canza bidiyo yana kunna asalin fayil ɗin bidiyo.

An lissafa dukkan hotunan wasu ɓangarori da wajibcin lasisinsu a docker/third-party-containers.yaml.

Haɗa mai samar da H5P

Quire ba ya haɗawa ko bayar da injin H5P ko ƙarin sabis (ADR 0019). Idan kana amfani da H5P, samar da rajistar masaukin girgije naka ko gudanar da naka H5P dabam da Quire. Yi masa rajista a matsayin kayan LTI 1.3 na waje, sannan ƙara abun cikinsa ga kwasa-kwasai a matsayin ayyukan kayan aiki. Quire yana musayar maki da ci gaban aiki/tantancewa ta LTI Assignment and Grade Services (AGS). Idan mai samarwa kuma yana aika kalaman xAPI, saita wannan daban ga ma’ajiyar kalaman xAPI ta Quire; musayar maki/ci gaba ta AGS ba ta aika kalaman xAPI ba. Shigo da Moodle yana bayyana cewa ayyukan H5P suna buƙatar haɗin kayan LTI. Mai samarwa ne har zuwa ƙarshe ke da alhakin injin H5P, rubuta abun ciki, ma’ajiyar abun ciki da tarihin ƙoƙari.

Domin gudanar da naka H5P a wannan uwar garke, saita QUIRE_H5P_IMAGE zuwa hotonsa kuma fara profile na h5p. Compose yana buɗe shi a QUIRE_H5P_PORT (8090) ya adana bayanansa a volume na h5p-data; hoton da wajibcinsa naka ne.

Saituna

Kowane tsari yana karanta docker/.env. Samfurin docker/.env.example yana lissafa kowane saiti da tsohonsa. Ƙungiyoyin:

Adiresoshi

Sirrika

Riƙe kwafin QUIRE_MASTER_KEY a wani wuri dabam da wannan uwar garke. Ma’ajiya da aka dawo ba za ta iya warware shaidar shiga da take riƙe ba idan babu shi.

Ma’ajiya

Ana amfani da kalmomin sirrin matsayi ne idan an ƙirƙiri volume na ma’ajiya a farkon lokaci. Domin canza ɗaya daga baya, yi amfani da ALTER ROLE, sannan sabunta URL mai dacewa.

QUIRE_REPORT_DATABASE_URL na ma’ajiya ta zahiri ce da DATABASE_URL ya nuna. Ga kowace ma’ajiya ta zahiri da aka yi rajista, saita nata URL na haɗin quire_report a muhallin yanar gizo da mai aiki, sannan saka sunan sauyin yanayi a filin Sauyin yanayin rahoto na ma’ajiyar a matsayin env:NAME. Dole nuni ya nuna ma’ajiya ɗaya da haɗin manhajar, zai fi kyau kwafin karatunta. Kowane fuskar rahoton tana bin ƙungiya zuwa haɗin rahoto na ma’ajiyarta: mai gina rahoto da rahotonnin da aka adana, isarwar jadawali, fitar da rahoto, nazari, rajistar tantancewa, albarkatun tantancewar REST da binciken tantancewa na mataimaki. Babu wanda ke aron URL na rahoton wata ma’ajiya. Idan ma’ajiya ba ta da haɗin rahoto, rahotanni na yau da kullum suna gudana ta haɗin manhajar ma’ajiyar kanta; amma nazari da duk karatun tantancewa suna ƙin aiki su faɗi dalili, domin matsayin manhaja ba zai iya karanta tarihin tantancewa ba.

Na’urorin aiki

Ana ƙin ƙimar na’urar da wannan siga ba ta ƙunsa ba yayin farawa na sashen yanar gizo, tare da ambaton saitin, maimakon a maye gurbinsa a ɓoye da tsohon ƙima.

Hotuna

Shafuka suna neman hotuna a girma huɗu tabbatattu ta /api/files/{id}/image/{size}, wanda ke duba izinin shiga iri ɗaya da fayil ɗin sannan ya karkatar zuwa hidimar hoto. Kowace ƙungiya na iya neman sabbin haɗin hoto da girma QUIRE_IMAGE_SPECS_PER_HOUR (tsoho 2000) a awa guda; ba a ƙirga girman da aka riga aka samar a wannan awa ba. Yi amfani da valkey ko postgres ga QUIRE_CACHE_DRIVER idan akwai kwantena yanar gizo fiye da ɗaya, domin iyakar ta yi aiki a cikinsu.

Cloudflare Images yana riƙe kwafin asalin kowane hoto da yake bayarwa. Idan an share fayil, mai aiki yana share wannan kwafi kafin asalin.

Jerin aiki

Ayyukan baya suna amfani da pg-boss a wannan ma’ajiya ta Postgres, saboda haka babu hidimar jerin aiki da za a gudanar ko saitawa. Ana sanya aiki cikin jerin a cikin ma’amala ɗaya da canjin da ya haifar da shi, don haka katsewa ba zai rasa shi ko aika shi sau biyu ba. QUIRE_QUEUE_DRIVER shi ne pgboss a nan, tsohonsa; vercel da cloudflare suna matsar da sanarwa da isar da webhook masu sauƙi kawai zuwa jerin aiki na dandalinsu, kuma jagororin Vercel da Cloudflare suna bayyana su da yadda sassan yanar gizonsu ke saka ayyuka.

Imel

Saita ɗaya daga cikin:

• QUIRE_EMAIL_PROVIDER_CONFIG: abun JSON mai nuna mai samar da HTTP da shaidar shiga, kamar {"provider":"postmark","token":"..."}. Ana goyon bayan Postmark, Amazon SES, Mailgun, SendGrid da Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Wannan manufa kaɗai ce; manufofin serverless suna toshe SMTP.

Mai aikawa shi ne QUIRE_MAIL_FROM. Domin gwada Quire, fara profile na devmail, saita QUIRE_SMTP_URL=smtp://mailpit:1025, sannan karanta imel a http://localhost:8025.

Hidimomi na zaɓi

Sa ido

OTEL_EXPORTER_OTLP_ENDPOINT yana nuna mai tattarawa da kowane tsari ke aika bibiyoyi da ma’aunai zuwa gare shi; tare da profile na observability shi ne http://otelcol:4318, kuma docker/otel-collector.yaml shi ne inda za ka ƙara mai fitar da bayanai na tsarinka. Idan an saita shi, sashen yanar gizo, mai aiki, mai tsara aiki, abun ciki da collab suna fitar da spans ta OTLP/HTTP (buƙatun yanar gizo, ma’amalolin ma’ajiya ta ƙungiya, ayyukan ma’aikaci da kiran waje), kuma suna aika ma’aunai zuwa wannan wuri kowane minti (OTEL_METRICS_EXPORTER=none yake kashe su). OTEL_TRACES_SAMPLER_ARG yana saita rabon bibiyoyin da za a riƙe. A LOG_LEVEL, ana aika log zuwa daidaitaccen fitarwa, Compose kuma yana juya su. Bibiyoyi ba sa ɗaukar bayanan mutum.

Fitar da bayanai bisa yanki (zama a EU)

QUIRE_REGION=eu yana nuna cewa tsarin yana yiwa ƙungiyoyin Tarayyar Turai hidu. Mai aiki yana riƙe duk buƙatun waje da aka yi wa ƙungiyar da aka kayyade ga EU bisa jerin izini (sashen 8.1 na 21-compliance.md). Jerin izini ya ƙunshi hosts da hidimomin da aka saita suka bayyana ga yankin (ƙarshen ma’ajiya, mai aika imel, mai samar da bidiyo na masaukin girgije, wuraren ajiyar ƙungiya, masu samar da AI da asusun imel), hosts na kowace hidima a ƙarƙashin keɓancewa mai aiki, da hosts ɗin da ka lissafa a QUIRE_EGRESS_ALLOW_HOSTS. Ana ƙin buƙatar zuwa wani host na jama’a kafin aikawa, ana rubuta ƙin a tarihin tantancewar ƙungiya a matsayin privacy/egress_refused, kuma ana lissafa shi ƙarƙashin Compliance, Data residency.

Ba a tilasta wa ƙungiyoyin UK da US jerin hosts; duba yankin hidima yana aiki garesu. Saita jerin ga mai aiki; shafin mai gudanarwa yana karanta shi a sashen yanar gizo domin nuna jerin, saboda haka saka shi a docker/.env, wanda kowane hidima ke karantawa.

Dubawar manhaja tana ba da kuskure bayyananne da shigarwar tantancewa, amma ba ita ce tabbaci ba: lamba na iya yin kuskure. Hanyar sadarwa ce tabbaci. Compose ba ya tilasta wannan. Ga tsarin yanki, saka hidimomin worker da web a hanyar sadarwa internal: true wadda hanya ɗaya tak zuwa waje ita ce wakilin fitar da bayanai (misali kwantenar Squid ko tinyproxy), wanda ke ba da izini ga hosts iri ɗaya da QUIRE_EGRESS_ALLOW_HOSTS tare da hosts na hidimomin da ka saita; sannan saita HTTPS_PROXY ga waɗannan hidimomin. Shafin zama a yanki yana lissafa ainihin hosts ɗin da manhaja ta yarda, saboda haka ana iya kwatanta jerin biyun.

Lafiya

docker compose -f docker/compose.yaml ps yana nuna lafiyar kowane hidima.

TLS

Hidimar proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) tana cikin tsarin tsoho. Tana amsawa a tashoshi 80 da 443, tana turawa zuwa:

init-env.sh yana samo QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL da IMGPROXY_URL daga asalin biyu, don haka ba sa rabuwa. Gyara su tare idan ka canza asali da hannu.

Takardun shaida suna bin QUIRE_PROXY_TLS:

• internal (tsoho): cibiyar takardar shaidar Caddy, ga localhost, *.localhost da lvh.me. Amince da tushe sau ɗaya sannan ka shiga:

  docker compose -f docker/compose.yaml cp \
    proxy:/data/caddy/pki/authorities/local/root.crt ./quire-local-ca.crt

  Ƙara quire-local-ca.crt zuwa ma’ajiyar amincewar tsarin ko burauza. curl yana karɓarsa ta --cacert.

• Adireshin imel: takardun ACME na atomatik (Let’s Encrypt, sannan ZeroSSL) ga ainihin sunayen hosts. Dole DNS na asali biyu da kowane host na ƙungiya su nuna nan, tashoshi 80 da 443 kuma su kasance a buɗe daga intanet.

Ana bayar da takardar host na ƙungiya bisa buƙata, a ziyarar farko, kuma sai idan web ya tabbatar sunan na wannan shigarwa ne (/tls-allowed, ana tambayarsa a hanyar Compose). Ba a buƙatar takardar wildcard ko plugin na mai samar da DNS, kuma baƙon da ya sa suna ya nuna uwar garken ba zai iya sa a nema masa takarda ba. Takardu da cibiyar amincewar gida suna cikin volume na caddy-data; yi musu ajiyar bayanai tare da sauran idan kana amfani da internal.

web yana amincewa da X-Forwarded-For daga wakilin baya kaɗai: wakilin yana da tsayayyen adireshi (QUIRE_PROXY_ADDRESS, tsoho 172.29.64.10) a ƙaramin yanki tsayayye (QUIRE_COMPOSE_SUBNET), kuma QUIRE_TRUSTED_PROXY_CIDRS yana bayyana wannan adireshin. Idan ƙaramin yanki ya yi karo da hanyar sadarwa a uwar garken, canza su duka biyu sannan gudanar da docker compose down kafin up.

Bayan wakilin baya naka

Domin amfani da mai rarraba zirga-zirga ko wakili da kake gudanarwa, bar proxy a kashe (docker compose up -d --scale proxy=0) sannan kawo ƙarshen TLS a gaban web (8080), content (8081), collab (1234, websocket) da centrifugo (8000, websocket). Saita adireshin jama’a a QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN da QUIRE_COLLAB_URL (wss://), da iyakar adireshin wakilinka a QUIRE_TRUSTED_PROXY_CIDRS.

Gyara matsaloli

• init ya fita da “QUIRE_DATABASE_ID is not a UUID”: saita shi da uuidgen.
• web yana sake farawa da “did not start on compose”: log yana lissafa kowane saiti da ba zai iya amfani da shi ba da abin da za a saita a madadinsa.
• Canza kalmar sirrin matsayi a .env bayan farawa na farko ba ya yin komai: rubutun saitawa sau ɗaya ne kawai ke gudana. Yi amfani da ALTER ROLE.
• Loda yana kasa da kuskuren binciken cuta yayin da aka saita CLAMAV_URL: ClamAV yana sauke sa hannunsa a farkon farawa, wannan yana ɗaukar ’yan mintuna.