Quiren asentaminen Docker Composella

Tämä asentaa koko tuotteen yhdelle isännälle: oppimisympäristön, taustatyöt, reaaliaikaisuus- ja yhteistyömuokkauspalvelut sekä profiileista valittavat lisäpalvelut. Rakenne kuvataan tiedoston docs/architecture/23-ops.md kohdassa 2.

Muut kohteet: Vercel ja Cloudflare Workers suorittavat vain verkkopalvelutason. Päivitykset käsitellään päivitysoppaassa, varmuuskopiot ja palautusharjoitus varmuuskopiointioppaassa.

Tarvittavat asiat

• Docker Engine 27 tai uudempi ja Compose-lisäosa 2.30 tai uudempi.
• Oletuspinolle 4 CPU-ydintä ja 8 Gt muistia; --profile full -valinnalla 8 ydintä ja 16 Gt muistia. Pelkät ClamAV:n allekirjoitustiedot käyttävät noin 1,5 Gt.
• Verkkotunnus verkkopalvelutasolle ja toinen epäluotettavalle sisällölle. Niiden on oltava eri palvelinnimiä: SCORM-paketit ja ladattu HTML suoritetaan sisältöalkuperässä, jotta ne eivät koskaan voi lukea oppimisympäristön evästeitä.
• Paikallista kokeilua varten lvh.me ja *.localhost osoittavat osoitteeseen 127.0.0.1, kuten docker/.env.example olettaa. Pinon oma proxy-palvelu palvelee molempia HTTPS-yhteydellä paikallisen varmenneviranomaisen avulla, joten muuta ei tarvitse asentaa (katso “TLS”).
• Isännän vapaat portit 80 ja 443 (QUIRE_PROXY_HTTP_PORT ja QUIRE_PROXY_HTTPS_PORT vaihtavat niitä).

Ensimmäinen käynnistys

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 luo tiedoston docker/.env mallista docker/.env.example ja muodostaa kaikki salaisuudet (tietokannan salasanat, allekirjoitus- ja pääavaimet sekä sisällön käynnistysavaimen parin). Se luo myös auditointitarkistuspisteen allekirjoitusavaimen tiedostoon docker/secrets/audit-signing-key.pem, jonka Compose liittää työntekijöille salaisuutena. Se tarvitsee vain komennot sh, awk ja openssl, eikä suostu korvaamaan olemassa olevaa docker/.env-tiedostoa. Kopioi molemmat tiedostot pois isännältä: ilman QUIRE_MASTER_KEY-avainta palautetussa tietokannassa olevia tunnistetietoja ei voi purkaa. Jos täytät tiedoston käsin, kopioi ensin komennolla cp docker/.env.example docker/.env; tiedostossa kerrotaan, miten kukin salaisuus luodaan.

Molempien alkuperäosoitteiden on käytettävä https-yhteyttä. Sisältöpalvelu ei hyväksy tuotannossa pelkkää HTTP:tä eivätkä osoitteet saa kuulua samaan rekisteröitävään verkkotunnukseen. proxy-palvelu päättää TLS-yhteyden kummallekin (katso “TLS”). init-env.sh hylkää http://-alkuiset osoitteet.

Pino käynnistyy kiinteässä järjestyksessä. Kukin vaihe odottaa edellisen valmistumista:

1. postgres muuttuu terveeksi. Ensimmäisellä käynnistyskerralla sen alustuskomentosarja (docker/postgres/init/90-passwords.sh) asettaa neljän roolin salasanat.
2. migrate suorittaa kaikki migraatiot ja alustaa työjonon ohjaustietokannassa sekä jokaisessa omistetussa vuokraajatietokannassa. Se varmistaa tietokantojen yhteneväisyyden ja päättyy sitten (katso docs/ops/upgrade.md). Migraatiot suoritetaan jokaisella käynnistyskerralla. Ne ovat idempotentteja, joten päivitykseen riittää uusi levykuva ja uudelleenkäynnistys.
3. init (apps/web/src/first-run.ts) kirjaa sovellustietokannan tunnisteen QUIRE_DATABASE_ID-arvolla. Jos QUIRE_SETUP_ADMIN_EMAIL on asetettu, se luo ensimmäisen organisaation ja sen ylläpitäjän. Kirjautumisosoite ja luotu salasana tulostetaan kerran komennon docker compose logs init lokiin.
4. Käynnistetään web, content, worker, scheduler, collab ja centrifugo.
5. proxy käynnistyy, kun web ja content ovat terveitä.

Avaa osoite https://demo. ja lisää sen perään sovelluksen verkkotunnus (tarkka kirjautumisosoite näkyy init-lokissa). Kirjaudu sisään. Luota paikallisen asennuksen tapauksessa ensin välityspalvelimen varmenneviranomaiseen (katso “TLS”). Vaihda luotu salasana osoitteessa /account/security.

Vaadittavan salaisuuden puuttuessa prosessi kieltäytyy käynnistymästä ja nimeää puuttuvan asetuksen lokissa. Osittain määritettyä kokoonpanoa ei käynnistetä.

Palvelut ja profiilit

--profile full käynnistää kaikki valinnaiset palvelut paitsi backup ja h5p. Käynnistä yksittäinen profiili komennolla docker compose -f docker/compose.yaml --profile scan up -d. Quire toimii ilman valinnaisia palveluja ja ilmoittaa, mitä puuttuu: ilman tarkistinta lataukset tallennetaan ilman haittaohjelmatarkistusta ja ylläpitäjälle kerrotaan siitä; ilman Gotenbergia tiedostot voi ladata mutta niitä ei esikatsella; ilman muunninta videot toistetaan alkuperäisinä.

Kaikki kolmannen osapuolen kuvat ja niiden lisenssivelvoitteet luetellaan tiedostossa docker/third-party-containers.yaml.

H5P-palveluntarjoajan yhdistäminen

Quire ei sisällä eikä toimita H5P-suoritusympäristöä tai apupalvelua (ADR 0019). Jos käytät H5P:tä, hanki oma isännöity tilaus tai ylläpidä H5P-asennusta erillään Quiresta. Rekisteröi tarjoaja ulkoisena LTI 1.3 -välineenä ja lisää sen sisältö kursseille välinetoimintoina. Quire vaihtaa arvosanat ja toiminnon tai arvioinnin edistymistiedot LTI Assignment and Grade Services (AGS) -palvelun kautta. Jos tarjoaja lähettää myös xAPI-tietueita, määritä erikseen yhteys Quiren xAPI-tietuevarastoon. AGS:n arvosana- ja edistymistietojen vaihto ei lähetä xAPI-tietueita. Moodle-tuonti ilmoittaa H5P-toiminnoista, jotka vaativat LTI-välineen. Tarjoaja vastaa edelleen H5P-suoritusympäristöstä, sisällön luomisesta, sisältöpankista ja yrityshistoriasta.

Jos haluat käyttää tällä isännällä omaa H5P-asennusta, aseta QUIRE_H5P_IMAGE sen levykuvaksi ja käynnistä h5p-profiili. Compose julkaisee sen portissa QUIRE_H5P_PORT (8090) ja säilyttää sen tiedot h5p-data-taltiolla. Levykuva ja siihen liittyvät velvoitteet pysyvät sinun vastuullasi.

Asetukset

Jokainen prosessi lukee tiedoston docker/.env. Malli docker/.env.example luettelee asetukset ja niiden oletukset. Ryhmät:

Osoitteet

Salaisuudet

Säilytä QUIRE_MASTER_KEY-avaimen kopio muualla kuin tällä isännällä. Ilman sitä palautettu tietokanta ei voi purkaa tallennettuja tunnistetietoja.

Tietokanta

Roolien salasanat asetetaan vain, kun tietokantataltio luodaan ensimmäisen kerran. Vaihda salasana myöhemmin komennolla ALTER ROLE ja päivitä vastaava yhteysosoite.

QUIRE_REPORT_DATABASE_URL koskee fyysistä tietokantaa, jonka DATABASE_URL määrittää. Aseta jokaiselle muulle rekisteröidylle fyysiselle tietokannalle sen oma quire_report-yhteysosoite verkkopalvelun ja työntekijän ympäristöön. Aseta sen jälkeen tietokannan Raportoinnin ympäristömuuttuja -kenttään muuttujan nimi muodossa env:NAME. Viitteen on osoitettava samaan tietokantaan kuin sovellusyhteyden, mieluiten sen lukureplikaan. Jokainen raporttinäkymä käyttää vuokraajan oman tietokannan raporttiyhteyttä: raporttien rakentaja ja tallennetut raportit, ajastetut toimitukset, raporttien viennit, analytiikka, auditointiloki, REST-auditointiresurssit ja avustajan auditointihaku. Mikään niistä ei käytä toisen tietokannan raporttiosoitetta. Jos tietokannalla ei ole raporttiyhteyttä, tavalliset raportit suoritetaan sen omalla sovellusyhteydellä. Analytiikka ja kaikki auditointiluvut hylätään ilmoituksella, sillä sovellusrooli ei voi lukea auditointiketjua.

Ajurit

Jos tämän julkaisun ajurivalikoimaan kuulumatonta arvoa käytetään, verkkopalvelun käynnistys hylätään ja virheessä nimetään asetus. Oletusarvoa ei oteta käyttöön hiljaisesti.

Kuvat

Sivut pyytävät kuvia neljässä kiinteässä koossa osoitteesta /api/files/{id}/image/{size}. Palvelu tarkistaa samat käyttöoikeudet kuin itse tiedostolle ja uudelleenohjaa kuvapalveluun. Jokainen organisaatio voi pyytää tunnissa enintään QUIRE_IMAGE_SPECS_PER_HOUR uutta kuva- ja kokoparia (oletus 2000). Sillä tunnilla jo tuotettuja kokoja ei lasketa mukaan. Jos käytössä on useampi verkkosäiliö, aseta valkey tai postgres ajuriksi muuttujaan QUIRE_CACHE_DRIVER, jotta raja on yhteinen.

Cloudflare Images säilyttää itse kopion jokaisesta tarjoamastaan alkuperäiskuvasta. Kun tiedosto poistetaan, työntekijä poistaa ensin tämän kopion ja sitten alkuperäisen.

Työjono

Taustatyöt käyttävät pg-bossia samassa Postgres-tietokannassa. Erillistä jonopalvelua ei tarvitse suorittaa eikä määrittää. Työt lisätään jonoon samassa tapahtumassa kuin ne käynnistävä muutos, joten kaatuminen ei voi kadottaa työtä tai lähettää sitä kahdesti. QUIRE_QUEUE_DRIVER on tässä oletusarvoinen pgboss. Ajurit vercel ja cloudflare siirtävät vain kevyet ilmoitus- ja webhook-toimitukset alustan omaan jonoon. Vercel- ja Cloudflare-oppaissa kuvataan niiden toiminta ja verkkopalvelutason jonoon lisäämät työt.

Sähköposti

Aseta jompikumpi seuraavista:

• QUIRE_EMAIL_PROVIDER_CONFIG: HTTP-palveluntarjoajan ja sen tunnistetiedot nimeävä JSON-objekti, esimerkiksi {"provider":"postmark","token":"..."}. Tuettuja ovat Postmark, Amazon SES, Mailgun, SendGrid ja Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Tämä kohde tukee asetusta; palvelimettomat kohteet estävät SMTP:n.

QUIRE_MAIL_FROM määrittää lähettäjän. Kokeillaksesi Quirea käynnistä devmail-profiili, aseta QUIRE_SMTP_URL=smtp://mailpit:1025 ja lue viestit osoitteesta http://localhost:8025.

Valinnaiset palvelut

Havainnoitavuus

OTEL_EXPORTER_OTLP_ENDPOINT määrittää kerääjän, jolle kaikki prosessit lähettävät jäljet ja mittarit. observability-profiilissa sen arvo on http://otelcol:4318. Lisää taustajärjestelmän vientipalvelu tiedostoon docker/otel-collector.yaml. Jos asetus on määritetty, verkkopalvelu, työntekijä, ajastin, sisältöpalvelu ja collab-prosessit vievät pyynnöistä, vuokraajien tietokantatapahtumista, työntekijätöistä ja lähtevistä kutsuista muodostetut jäljet OTLP/HTTP:llä sekä mittarit samaan osoitteeseen minuutin välein. OTEL_METRICS_EXPORTER=none poistaa mittarit käytöstä. OTEL_TRACES_SAMPLER_ARG määrittää säilytettävien jälkien osuuden. Lokit kirjoitetaan vakiotulosteeseen muuttujalla LOG_LEVEL määritetyllä tasolla, ja Compose kierrättää ne. Jäljissä ei ole henkilötietoja.

Alueellinen ulosmenevä liikenne (EU:n tietojen sijainti)

QUIRE_REGION=eu kertoo pinon palvelevan Euroopan unionin organisaatioita. Työntekijä rajaa tämän jälkeen EU-alueeseen kiinnitetyn organisaation kaikki lähtevät pyynnöt sallittujen listaan (21-compliance.md, kohta 8.1). Lista sisältää niiden määritettyjen palvelujen isännät, jotka ilmoittavat toimivansa alueella (tallennuspäätepiste, sähköpostipalvelu, isännöity videopalvelu, organisaation omat tallennuskohteet, tekoälypalvelut ja sähköpostitili), aktiivisen poikkeusluvan alaisten palvelujen isännät sekä muuttujassa QUIRE_EGRESS_ALLOW_HOSTS luettelemasi isännät. Pyyntö muihin julkisiin osoitteisiin estetään ennen lähetystä. Esto kirjataan organisaation auditointiketjuun tunnisteella privacy/egress_refused sekä kohdassa Compliance, Data residency.

Isäntänimilista ei koske Ison-Britannian eikä Yhdysvaltojen organisaatioita. Niille tehdään edelleen palvelun alueen tarkistukset. Aseta lista työntekijälle. Ylläpitosivu lukee sen verkkopalvelutasolta ja näyttää sallitut isännät. Lisää muuttuja siis tiedostoon docker/.env, jota kaikki palvelut lukevat.

Sovelluksen tarkistus antaa selkeän virheen ja auditointimerkinnän, mutta se ei ole varsinainen takuu, sillä koodi voi olla virheellistä. Takuun muodostaa verkko. Compose ei valvo sitä puolestasi. Alueellisessa pinossa aseta worker- ja web-palvelut verkkoon internal: true, jonka ainoa ulospääsy on ulosmenevää liikennettä välittävä palvelin (esimerkiksi Squid tai tinyproxy-säiliö). Rajaa se samoihin osoitteisiin kuin QUIRE_EGRESS_ALLOW_HOSTS sekä määrittämiesi palvelujen isäntiin. Aseta palveluille myös HTTPS_PROXY. Alueellisen sijainnin sivu näyttää sovelluksen sallimat osoitteet, jotta voit verrata luetteloita.

Terveys

docker compose -f docker/compose.yaml ps näyttää jokaisen palvelun terveystilan.

TLS

Oletuspino sisältää proxy-palvelun (Caddy, Apache-2.0, docker/caddy/Caddyfile). Se kuuntelee portteja 80 ja 443 ja reitittää pyynnöt näin:

init-env.sh johtaa kahdesta alkuperäosoitteesta asetukset QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL ja IMGPROXY_URL, jotta ne eivät voi ajautua eri arvoihin. Muuta ne yhdessä, jos vaihdat alkuperäosoitetta käsin.

Varmenteet määräytyvät asetuksen QUIRE_PROXY_TLS mukaan:

• internal (oletus): Caddyn oma varmenneviranomainen osoitteille localhost, *.localhost ja lvh.me. Luota sen juurivarmenteeseen kerran ja avaa sitten sivusto:

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

  Lisää quire-local-ca.crt järjestelmän tai selaimen luotettujen varmenteiden joukkoon. curl-komennossa käytetään valintaa --cacert.

• Sähköpostiosoite: automaattiset ACME-varmenteet (Let’s Encrypt, sitten ZeroSSL) oikeille verkkotunnuksille. Molempien alkuperäosoitteiden ja jokaisen vuokraajan isännän DNS-tietojen on osoitettava tänne, ja porttien 80 ja 443 on oltava saavutettavissa internetistä.

Vuokraajien isännille myönnetään varmenne tarpeen mukaan ensimmäisen käynnin yhteydessä, ja vain jos web-palvelu varmistaa, että nimi kuuluu asennukseen (kysely /tls-allowed Compose-verkossa). Wildcard-varmennetta tai DNS-palveluntarjoajan liitännäistä ei tarvita. Väärän verkkotunnuksen tähän isäntään osoittava ulkopuolinen ei voi pakottaa varmenteen pyytämistä. Varmenteet ja paikallinen varmenneviranomainen säilyvät caddy-data-taltiolla. Jos käytät internal-asetusta, varmuuskopioi taltio muiden mukana.

Web-palvelu luottaa välityspalvelimen X-Forwarded-For-otsakkeeseen. Välityspalvelimen osoite on kiinteä (QUIRE_PROXY_ADDRESS, oletus 172.29.64.10) ja se on kiinteässä aliverkossa (QUIRE_COMPOSE_SUBNET). QUIRE_TRUSTED_PROXY_CIDRS nimeää kyseisen osoitteen. Jos aliverkko on ristiriidassa isäntäkoneen verkon kanssa, vaihda molemmat asetukset ja suorita docker compose down ennen up-komentoa.

Oman käänteisvälityspalvelimen takana

Jos käytät nykyistä kuormantasaajaa tai välityspalvelinta, älä sisällytä proxy-palvelua (docker compose up -d --scale proxy=0). Päätä TLS-yhteys niiden palvelujen edessä: web (8080), content (8081), collab (1234, WebSocket) ja centrifugo (8000, WebSocket). Aseta julkiset osoitteet muuttujiin QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN ja QUIRE_COLLAB_URL (wss://) sekä välityspalvelimen osoitealue muuttujaan QUIRE_TRUSTED_PROXY_CIDRS.

Vianmääritys

• init pysähtyy viestiin “QUIRE_DATABASE_ID is not a UUID”: aseta tunniste komennolla uuidgen.
• web käynnistyy uudelleen ja ilmoittaa “did not start on compose”: lokissa luetellaan asetukset, joita ei voida käyttää, ja niiden korvaamiseen tarvittavat arvot.
• Roolin salasanan vaihtaminen .env-tiedostossa ensimmäisen käynnistyksen jälkeen ei vaikuta: alustusskripti ajetaan vain kerran. Käytä ALTER ROLE -komentoa.
• Lataus epäonnistuu tarkistusvirheeseen, kun CLAMAV_URL on asetettu: ClamAV lataa allekirjoitustietonsa ensimmäisellä käynnistyskerralla, mikä kestää muutaman minuutin.