Instalacija Quirea pomoću Docker Composea

Ovo je cijeli proizvod na jednom poslužitelju: LMS, pozadinska obrada, usluge za rad u stvarnom vremenu i zajedničko uređivanje te sve neobavezne usluge koje se pokreću putem profila. Dizajn je opisan u odjeljku 2 dokumenta docs/architecture/23-ops.md.

Ostala odredišta: Vercel i Cloudflare Workers pokreću samo web sloj. Nadogradnje su opisane u upgrade.md, a sigurnosne kopije i proba vraćanja u backup-restore.md.

Što vam je potrebno

• Docker Engine 27 ili noviji s dodatkom Compose 2.30 ili novijim.
• Četiri procesorske jezgre i 8 GB memorije za zadani skup usluga; 8 jezgri i 16 GB uz --profile full (ClamAV sam zauzima oko 1,5 GB za potpise).
• DNS naziv za web sloj i drugi za nepouzdani sadržaj. Moraju biti na različitim domaćinima: paketi SCORM i preneseni HTML pokreću se na izvornom poslužitelju sadržaja kako nikad ne bi mogli čitati kolačiće LMS-a.
• Za lokalno testiranje, lvh.me i *.localhost razrješavaju se na 127.0.0.1, kako je postavljeno u docker/.env.example. Vlastita usluga skupa proxy poslužuje oba naziva putem HTTPS-a s lokalnim izdavateljem certifikata, pa se ništa drugo ne mora instalirati (pogledajte „TLS”).
• Slobodni portovi 80 i 443 na poslužitelju (QUIRE_PROXY_HTTP_PORT i QUIRE_PROXY_HTTPS_PORT mijenjaju ih).

Prvo pokretanje

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 stvara docker/.env iz datoteke docker/.env.example, generira sve tajne (lozinke baza podataka, ključeve za potpisivanje i glavni ključ te par ključeva za pokretanje sadržaja) i zapisuje ključ za potpisivanje kontrolne točke nadzora u docker/secrets/audit-signing-key.pem. Compose tu datoteku priključuje radnicima kao tajnu. Potrebni su samo sh, awk i openssl, a postojeću datoteku docker/.env odbija prebrisati. Obje datoteke kopirajte izvan poslužitelja: bez QUIRE_MASTER_KEY vraćena baza ne može dešifrirati pohranjene vjerodajnice. Ako datoteku želite popuniti ručno, pokrenite cp docker/.env.example docker/.env; u datoteci je objašnjeno kako generirati svaku tajnu.

Oba izvora moraju koristiti https: usluga sadržaja u produkciji odbija obični HTTP, a izvori ne smiju dijeliti registrabilnu domenu. Usluga proxy završava TLS vezu za oba (pogledajte „TLS”); init-env.sh odbija izvor s prefiksom http://.

Skup usluga pokreće se utvrđenim redoslijedom, a svaki korak čeka prethodni:

1. postgres postaje zdrav. Pri prvom pokretanju njegova inicijalizacijska skripta (docker/postgres/init/90-passwords.sh) postavlja lozinke četiriju uloga.
2. migrate primjenjuje sve migracije i postavlja red poslova u upravljačkoj bazi i u svakoj namjenskoj bazi klijenta, provjerava podudaraju li se, pa se gasi (docs/ops/upgrade.md). Migracije se pokreću pri svakom pokretanju i idempotentne su, pa se nadogradnja svodi na novu sliku i ponovno pokretanje.
3. init (apps/web/src/first-run.ts) bilježi bazu aplikacije pod nazivom QUIRE_DATABASE_ID te, ako je postavljeno QUIRE_SETUP_ADMIN_EMAIL, stvara prvu organizaciju i njezina administratora. Adresa za prijavu i generirana lozinka ispisuju se samo jednom u izlazu naredbe docker compose logs init.
4. Pokreću se web, content, worker, scheduler, collab i centrifugo.
5. proxy se pokreće kad web i content postanu zdravi.

Otvorite https://demo. iza čega slijedi domena aplikacije (zapis init ispisuje točnu adresu za prijavu) i prijavite se. Na lokalnoj instalaciji najprije vjerujte izdavatelju certifikata posrednika (pogledajte „TLS”). Promijenite generiranu lozinku na /account/security.

Proces koji se pokrene bez obavezne tajne odbija rad i u zapis navodi nedostajuću postavku. Ništa se ne pokreće s nepotpunom konfiguracijom.

Usluge i profili

--profile full pokreće sve neobavezne usluge osim backup i h5p. Pojedinu pokrenite naredbom docker compose -f docker/compose.yaml --profile scan up -d. Quire radi i bez neobaveznih usluga te navodi što nedostaje: bez skenera se prenesene datoteke pohranjuju bez skeniranja, a administrator dobiva obavijest; bez Gotenberga datoteke se mogu preuzeti umjesto da se prikaže pretpregled; bez pretvarača video se reproducira kao izvorna datoteka.

Sve slike trećih strana i pripadajuće obveze licenciranja navedene su u docker/third-party-containers.yaml.

Povezivanje pružatelja H5P-a

Quire ne ugrađuje niti isporučuje izvršno okruženje ili pomoćni proces H5P-a (ADR 0019). Ako koristite H5P, sami osigurajte hostiranu pretplatu ili upravljajte vlastitom, odvojeno hostiranom instancom H5P-a. Registrirajte pružatelja kao vanjski alat LTI 1.3 i dodajte njegov sadržaj kolegijima kao aktivnosti alata. Quire razmjenjuje ocjene te napredak aktivnosti i ocjenjivanja kroz LTI Assignment and Grade Services (AGS). Ako pružatelj šalje i iskaze xAPI-ja, zasebno ga konfigurirajte za Quireovo spremište iskaza xAPI-ja; razmjena ocjena i napretka putem AGS-a ne šalje iskaze xAPI-ja. Uvozi iz Moodla prikazuju aktivnosti H5P-a kao one kojima je potrebna veza s alatom LTI. Pružatelj je i dalje odgovoran za izvršno okruženje H5P-a, izradu sadržaja, bazu sadržaja i povijest pokušaja.

Da biste vlastitu instancu hostirali na ovom poslužitelju, postavite QUIRE_H5P_IMAGE na njezinu sliku i pokrenite profil h5p. Compose je objavljuje na QUIRE_H5P_PORT (8090), a podatke čuva u volumenu h5p-data; slika i sve povezane obveze ostaju vaša odgovornost.

Postavke

Svaki proces čita docker/.env. Predložak docker/.env.example navodi svaku postavku sa zadanom vrijednošću. Skupine su:

Adrese

Tajne

Sačuvajte kopiju QUIRE_MASTER_KEY izvan ovog poslužitelja. Vraćena baza bez njega ne može dešifrirati vjerodajnice koje sadrži.

Baza podataka

Lozinke uloga primjenjuju se samo pri prvoj izradi volumena baze podataka. Želite li ih promijeniti kasnije, upotrijebite ALTER ROLE, a zatim nadogradite odgovarajući URL.

QUIRE_REPORT_DATABASE_URL koristi se za fizičku bazu postavljenu u DATABASE_URL. Za svaku drugu registriranu fizičku bazu postavite njezin URL veze quire_report u okruženjima web sloja i radnika, a zatim naziv varijable upišite u polje Reporting environment variable te baze kao env:NAME. Referenca mora pokazivati na istu bazu kao i veza aplikacije, po mogućnosti na njezinu repliku samo za čitanje. Svaka površina za izvješća prati klijenta do veze za izvješća vlastite baze: alat za izradu izvješća i spremljena izvješća, zakazana slanja, izvozi izvješća, analitika, zapis nadzora, resursi nadzora REST i pretraživanje nadzora pomoćnikom. Nijedna ne koristi URL za izvješća druge baze. Ako baza nema vezu za izvješća, uobičajena se izvješća izvršavaju preko vlastite veze aplikacije te baze, dok analitika i sva čitanja nadzora odbijaju rad i objašnjavaju razlog jer uloga aplikacije ne može čitati trag nadzora.

Upravljački programi

Ako ova verzija ne sadrži vrijednost upravljačkog programa, pokretanje web sloja odbija je i navodi postavku umjesto da je tiho zamijeni zadanom.

Slike

Stranice traže slike u četiri fiksne veličine putem /api/files/{id}/image/{size}. Ta putanja provjerava isti pristup kao i za samu datoteku, a zatim preusmjerava na uslugu slika. Svaka organizacija može zatražiti QUIRE_IMAGE_SPECS_PER_HOUR (zadano 2000) novih parova slika i veličina na sat; veličine već izrađene tijekom tog sata ne računaju se. Koristite valkey ili postgres za QUIRE_CACHE_DRIVER uz više web-spremnika kako bi ograničenje vrijedilo u svima.

Cloudflare Images čuva vlastitu kopiju svakog izvornika koji poslužuje. Kad se datoteka izbriše, radnik briše tu kopiju prije izvornika.

Red poslova

Pozadinski poslovi koriste pg-boss u istoj bazi Postgresa, pa nije potrebno pokretati zasebnu uslugu reda ni išta konfigurirati. Poslovi se stavljaju u red u istoj transakciji kao i promjena koja ih je pokrenula, pa rušenje ne može izgubiti posao ni ga poslati dvaput. Ovdje je QUIRE_QUEUE_DRIVER postavljen na zadanu vrijednost pgboss; vercel i cloudflare premještaju samo lake obavijesti i isporuke web-dojavnika u vlastiti red platforme. Vodiči za Vercel i Cloudflare objašnjavaju kako web-slojevi tih platformi stavljaju poslove u red.

E-pošta

Postavite jedno od sljedećeg:

• QUIRE_EMAIL_PROVIDER_CONFIG: JSON objekt koji navodi HTTP pružatelja i njegove vjerodajnice, primjerice {"provider":"postmark","token":"..."}. Podržani su Postmark, Amazon SES, Mailgun, SendGrid i Resend.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Ovo odredište podržava tu postavku; poslužiteljski odredišni sustavi blokiraju SMTP.

QUIRE_MAIL_FROM adresa je pošiljatelja. Da biste isprobali Quire, pokrenite profil devmail, postavite QUIRE_SMTP_URL=smtp://mailpit:1025 i čitajte poštu na http://localhost:8025.

Neobavezne usluge

Nadzor

OTEL_EXPORTER_OTLP_ENDPOINT označava sakupljač kojem svaki proces šalje praćenja i metrike. Uz profil observability njegova je vrijednost http://otelcol:4318; u datoteci docker/otel-collector.yaml dodaje se izvoznik za vašu pozadinsku uslugu. Kad je postavljen, web sloj, radnik, planer, sadržajni poslužitelj i collab izvoze raspona putem OTLP/HTTP-a (web-zahtjevi, transakcije baza klijenata, poslovi radnika i odlazni pozivi) te svake minute šalju metrike na istu adresu (OTEL_METRICS_EXPORTER=none isključuje ih). OTEL_TRACES_SAMPLER_ARG postavlja udio zadržanih praćenja. Zapisi se ispisuju na standardni izlaz na razini LOG_LEVEL, a Compose ih rotira. Praćenja nikad ne sadrže osobne podatke.

Regionalni izlazni promet (rezidentnost podataka u EU-u)

QUIRE_REGION=eu znači da skup usluga poslužuje organizacije iz Europske unije. Radnik tada sva odlazna usmjerenja za organizaciju prikvačenu na EU ograničava popisom dopuštenih odredišta (odjeljak 8.1 dokumenta 21-compliance.md). Popis obuhvaća domaćine koje za regiju navode konfigurirane usluge (krajnju točku pohrane, pružatelja e-pošte, hostiranog videopružatelja, ciljeve vlastite pohrane organizacije, pružatelje umjetne inteligencije i račun e-pošte), domaćine usluga obuhvaćenih aktivnim izuzećem i domaćine koje navedete u QUIRE_EGRESS_ALLOW_HOSTS. Zahtjev prema bilo kojem drugom javnom domaćinu odbija se prije slanja, odbijanje se bilježi u tragu nadzora organizacije kao privacy/egress_refused, a domaćin se prikazuje u odjeljku Compliance, Data residency.

Organizacije iz UK-a i SAD-a ne ograničavaju se popisom domaćina; za njih i dalje vrijede provjere regije usluge. Popis postavite radniku, a stranica administracije čita ga u web-sloju radi prikaza dopuštenih odredišta, pa ga upišite u docker/.env, koji čitaju sve usluge.

Provjera aplikacije daje jasnu pogrešku i zapis nadzora, ali nije jamstvo: kod može biti pogrešan. Jamstvo pruža mreža, a Compose ga ne provodi umjesto vas. Za regionalni skup povežite usluge worker i web s mrežom internal: true kojoj je jedina izlazna ruta posrednički poslužitelj za izlazni promet (primjerice spremnik Squid ili tinyproxy) koji dopušta iste domaćine kao QUIRE_EGRESS_ALLOW_HOSTS, uz domaćine konfiguriranih usluga, i postavite HTTPS_PROXY za te usluge. Stranica rezidentnosti navodi točne domaćine koje aplikacija dopušta, pa možete usporediti oba popisa.

Zdravlje

docker compose -f docker/compose.yaml ps prikazuje stanje svake usluge.

TLS

Usluga proxy (Caddy, licenca Apache-2.0, docker/caddy/Caddyfile) dio je zadane konfiguracije. Odgovara na portovima 80 i 443 te usmjerava:

init-env.sh izvodi QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL i IMGPROXY_URL iz obaju izvora kako se njihove vrijednosti ne bi razišle. Ako ručno promijenite izvor, uređujte ih zajedno.

Certifikati ovise o QUIRE_PROXY_TLS:

• internal (zadano): vlastiti izdavatelj certifikata Caddyja za localhost, *.localhost i lvh.me. Jednom vjerujte njegovom korijenskom certifikatu, a zatim otvorite:

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

  Dodajte quire-local-ca.crt u spremište pouzdanih certifikata sustava ili preglednika. curl ga koristi putem opcije --cacert.

• Adresa e-pošte: automatski ACME certifikati (Let’s Encrypt, zatim ZeroSSL) za stvarne nazive domaćina. DNS za oba izvora i sve domaćine klijenata mora pokazivati ovamo, a portovi 80 i 443 moraju biti dostupni s interneta.

Certifikati za domaćine klijenata izdaju se na zahtjev pri prvom posjetu, i to samo kad web-sloj potvrdi da naziv pripada ovoj instalaciji putem /tls-allowed na mreži Composea. Nije potreban zamjenski certifikat ni dodatak pružatelja DNS usluge, a neznanac ne može postaviti naziv koji pokazuje na ovaj poslužitelj i time zatražiti certifikat. Certifikati i lokalni izdavatelj nalaze se u volumenu caddy-data; koristite li internal, uključite ga u sigurnosne kopije.

Web-sloj vjeruje zaglavlju X-Forwarded-For samo od posrednika: posrednik ima fiksnu adresu (QUIRE_PROXY_ADDRESS, zadano 172.29.64.10) u fiksnoj podmreži (QUIRE_COMPOSE_SUBNET), a QUIRE_TRUSTED_PROXY_CIDRS navodi tu adresu. Ako se podmreža preklapa s mrežom na poslužitelju, promijenite obje postavke, pokrenite docker compose down, a zatim up.

Iza vlastitog povratnog posredničkog poslužitelja

Želite li umjesto toga koristiti postojeći uravnoteživač opterećenja ili posrednički poslužitelj, izostavite proxy (docker compose up -d --scale proxy=0) i završite TLS ispred web (8080), content (8081), collab (1234, WebSocket) i centrifugo (8000, WebSocket). Postavite javne adrese u QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN i QUIRE_COLLAB_URL (wss://), a raspon adresa posrednika u QUIRE_TRUSTED_PROXY_CIDRS.

Rješavanje problema

• init završava uz poruku „QUIRE_DATABASE_ID is not a UUID”: postavite ga naredbom uuidgen.
• web se ponovno pokreće uz poruku „did not start on compose”: zapis navodi svaku postavku koju ne može podržati i prikazuje što umjesto nje treba koristiti.
• Promjena lozinke uloge u .env nakon prvog pokretanja nema učinka: inicijalizacijska skripta pokreće se samo jednom. Upotrijebite ALTER ROLE.
• Prijenos ne uspijeva zbog pogreške skeniranja dok je postavljen CLAMAV_URL: ClamAV pri prvom pokretanju preuzima potpise, što traje nekoliko minuta.