Memasang Quire dengan Docker Compose

Ini adalah produk lengkap di satu host: LMS, pekerjaan latar belakangnya, layanan penyuntingan kolaboratif dan waktu nyata, serta semua layanan opsional di balik profil. Rancangannya dijelaskan di bagian 2 docs/architecture/23-ops.md.

Target lainnya: Vercel dan Cloudflare Workers hanya menjalankan tingkat web. Prosedur peningkatan versi ada di upgrade.md, sedangkan pencadangan dan latihan pemulihan ada di backup-restore.md.

Yang Anda perlukan

• Docker Engine 27 atau yang lebih baru dengan plugin Compose 2.30 atau yang lebih baru.
• 4 inti CPU dan memori 8 GB untuk tumpukan bawaan; 8 inti dan 16 GB dengan --profile full (ClamAV sendiri menggunakan sekitar 1,5 GB untuk tanda tangan).
• Nama DNS untuk tingkat web dan nama kedua untuk konten tak tepercaya. Keduanya harus merupakan host yang berbeda: paket SCORM dan HTML yang diunggah berjalan di origin konten agar tidak pernah dapat membaca cookie LMS.
• Untuk pengujian lokal, lvh.me dan *.localhost mengarah ke 127.0.0.1, sebagaimana digunakan oleh docker/.env.example. Layanan proxy milik tumpukan menyajikan keduanya melalui https dengan otoritas sertifikat lokal, jadi tidak perlu memasang apa pun lagi (lihat “TLS”).
• Port 80 dan 443 harus tersedia di host (QUIRE_PROXY_HTTP_PORT dan QUIRE_PROXY_HTTPS_PORT dapat memindahkannya).

Menjalankan pertama kali

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 membuat docker/.env dari docker/.env.example dengan semua rahasia yang sudah dibuat (kata sandi basis data, kunci penandatanganan dan utama, pasangan kunci peluncuran konten), serta kunci penandatanganan titik pemeriksaan audit di docker/secrets/audit-signing-key.pem, yang dipasang Compose ke worker sebagai rahasia. Skrip ini hanya memerlukan sh, awk, dan openssl, serta menolak menimpa docker/.env yang sudah ada. Salin kedua berkas tersebut ke luar host: tanpa QUIRE_MASTER_KEY, basis data yang dipulihkan tidak dapat mendekripsi kredensial tersimpannya. Untuk mengisi berkas secara manual, jalankan cp docker/.env.example docker/.env; berkas itu menjelaskan cara membuat setiap rahasia.

Kedua origin harus menggunakan https: layanan konten menolak http biasa di lingkungan produksi, dan keduanya tidak boleh berbagi domain yang dapat diregistrasikan. Layanan proxy mengakhiri TLS untuk keduanya (lihat “TLS”); init-env.sh menolak origin http://.

Tumpukan dimulai dalam urutan tetap, dan setiap langkah menunggu langkah sebelumnya:

1. postgres menjadi sehat. Pada permulaan pertama, skrip inisialisasinya (docker/postgres/init/90-passwords.sh) menyetel empat kata sandi peran.
2. migrate menerapkan semua migrasi dan menyiapkan antrean pekerjaan di basis data kontrol serta di setiap basis data penyewa khusus, memeriksa kesesuaian semuanya, lalu keluar (docs/ops/upgrade.md). Migrasi dijalankan setiap kali mulai dan bersifat idempoten, jadi peningkatan versi cukup dengan image baru dan memulai ulang.
3. init (apps/web/src/first-run.ts) mendaftarkan basis data aplikasi di bawah QUIRE_DATABASE_ID dan, jika QUIRE_SETUP_ADMIN_EMAIL disetel, membuat organisasi pertama beserta administratornya. Alamat masuk dan kata sandi yang dibuat dicetak sekali di docker compose logs init.
4. web, content, worker, scheduler, collab, dan centrifugo dimulai.
5. proxy dimulai setelah web dan content sehat.

Buka https://demo. diikuti domain aplikasi Anda (log init mencetak alamat masuk yang tepat), lalu masuk. Pada instalasi lokal, percayai dahulu otoritas sertifikat proxy (lihat “TLS”). Ganti kata sandi yang dibuat di /account/security.

Proses yang dimulai tanpa rahasia wajib akan menolak berjalan dan menyebutkan pengaturan yang hilang di lognya. Tidak ada proses yang berjalan dengan konfigurasi setengah jadi.

Layanan dan profil

--profile full memulai semua layanan opsional kecuali backup dan h5p. Mulai satu profil dengan docker compose -f docker/compose.yaml --profile scan up -d. Tanpa layanan opsional, Quire tetap berfungsi dan memberi tahu apa yang tidak tersedia: tanpa pemindai, unggahan disimpan tanpa pemindaian dan administrator diberi tahu; tanpa Gotenberg, berkas dapat diunduh alih-alih menampilkan pratinjau; tanpa transcoder, video diputar sebagai berkas aslinya.

Setiap image pihak ketiga dan kewajiban lisensinya tercantum di docker/third-party-containers.yaml.

Menghubungkan penyedia H5P

Quire tidak menyematkan atau mengirimkan runtime H5P maupun sidecar (ADR 0019). Jika Anda menggunakan H5P, sediakan langganan yang dihosting sendiri atau operasikan instans H5P mandiri yang dihosting sendiri, terpisah dari Quire. Daftarkan penyedia tersebut sebagai alat eksternal LTI 1.3 dan tambahkan kontennya ke kursus sebagai aktivitas alat. Quire bertukar nilai dan progres aktivitas/penilaian melalui LTI Assignment and Grade Services (AGS). Jika penyedia juga mengirim pernyataan xAPI, konfigurasikan hal itu secara terpisah untuk penyimpanan pernyataan xAPI Quire; pertukaran nilai/progres AGS tidak mengirim pernyataan xAPI. Impor Moodle melaporkan aktivitas H5P sebagai aktivitas yang memerlukan koneksi alat LTI. Penyedia tetap bertanggung jawab atas runtime H5P, pembuatan materi, bank konten, dan riwayat percobaan.

Untuk menjalankan instans mandiri milik Anda di host ini, setel QUIRE_H5P_IMAGE ke imagenya dan mulai profil h5p. Compose memublikasikannya pada QUIRE_H5P_PORT (8090) dan menyimpan datanya di volume h5p-data; image dan kewajiban yang menyertainya tetap menjadi tanggung jawab Anda.

Pengaturan

Setiap proses membaca docker/.env. Templat docker/.env.example mencantumkan setiap pengaturan beserta nilai bawaannya. Kelompok pengaturan:

Alamat

Rahasia

Simpan salinan QUIRE_MASTER_KEY di tempat selain host ini. Basis data yang dipulihkan tanpanya tidak dapat mendekripsi kredensial di dalamnya.

Basis data

Kata sandi peran hanya diterapkan saat volume basis data dibuat pertama kali. Untuk mengubahnya kemudian, gunakan ALTER ROLE, lalu perbarui URL yang sesuai.

QUIRE_REPORT_DATABASE_URL digunakan untuk basis data fisik yang dikonfigurasi oleh DATABASE_URL. Untuk basis data fisik terdaftar lainnya, setel URL koneksi quire_report tersendiri di lingkungan web dan worker, lalu masukkan nama variabel tersebut di kolom Variabel lingkungan pelaporan pada basis data itu sebagai env:NAME. Referensi tersebut harus menunjuk ke basis data yang sama dengan koneksi aplikasinya, idealnya replika baca. Setiap permukaan pelaporan mengikuti penyewa ke koneksi laporan milik basis datanya sendiri: pembuat laporan dan laporan tersimpan, pengiriman terjadwal, ekspor laporan, analitik, log audit, sumber daya audit REST, serta pencarian audit oleh asisten. Tidak satu pun menggunakan URL laporan milik basis data lain. Jika basis data tidak memiliki koneksi laporan, laporan biasa berjalan pada koneksi aplikasinya sendiri, sedangkan analitik dan setiap pembacaan audit menolak permintaan dan menjelaskan alasannya, karena peran aplikasi tidak dapat membaca jejak audit.

Driver

Nilai driver yang tidak disertakan dalam rilis ini akan ditolak saat tingkat web dimulai, dengan nama pengaturannya, alih-alih diam-diam diganti dengan nilai bawaan.

Gambar

Halaman meminta gambar dalam empat ukuran tetap melalui /api/files/{id}/image/{size}. Endpoint ini memeriksa akses yang sama seperti berkasnya, lalu mengalihkan permintaan ke layanan gambar. Setiap organisasi dapat meminta pembuatan paling banyak QUIRE_IMAGE_SPECS_PER_HOUR (bawaan 2000) pasangan gambar dan ukuran baru per jam; ukuran yang sudah dibuat pada jam itu tidak dihitung. Gunakan valkey atau postgres untuk QUIRE_CACHE_DRIVER jika ada lebih dari satu kontainer web agar batasnya berlaku di semua kontainer.

Cloudflare Images menyimpan salinannya sendiri dari setiap gambar asli yang disajikan. Saat berkas dihapus, worker menghapus salinan tersebut sebelum menghapus aslinya.

Antrean

Pekerjaan latar belakang menggunakan pg-boss di basis data Postgres yang sama, jadi tidak ada layanan antrean yang perlu dijalankan ataupun dikonfigurasi. Pekerjaan dimasukkan ke antrean dalam transaksi yang sama dengan perubahan pemicunya, sehingga kerusakan tidak akan menghilangkan pekerjaan ataupun mengirimkannya dua kali. QUIRE_QUEUE_DRIVER bernilai bawaan pgboss di sini; vercel dan cloudflare memindahkan hanya pengiriman notifikasi ringan dan webhook ke antrean milik platform. Panduan Vercel dan Cloudflare menjelaskan antrean tersebut dan cara tingkat webnya memasukkan pekerjaan.

Email

Setel salah satu dari:

• QUIRE_EMAIL_PROVIDER_CONFIG: objek JSON yang menyebutkan penyedia HTTP dan kredensialnya, misalnya {"provider":"postmark","token":"..."}. Postmark, Amazon SES, Mailgun, SendGrid, dan Resend didukung.
• QUIRE_SMTP_URL: smtp://user:password@host:587. Hanya untuk target ini; target tanpa server memblokir SMTP.

QUIRE_MAIL_FROM adalah alamat pengirim. Untuk mencoba Quire, mulai profil devmail, setel QUIRE_SMTP_URL=smtp://mailpit:1025, lalu baca email di http://localhost:8025.

Layanan opsional

Observabilitas

OTEL_EXPORTER_OTLP_ENDPOINT menentukan kolektor tujuan pengiriman trace dan metrik oleh setiap proses. Dengan profil observability, nilainya http://otelcol:4318, dan docker/otel-collector.yaml adalah tempat untuk menambahkan eksportir backend Anda. Jika disetel, proses web, worker, scheduler, content, dan collab mengekspor span melalui OTLP/HTTP (permintaan web, transaksi basis data penyewa, pekerjaan worker, dan panggilan keluar), serta mengirim metrik ke endpoint yang sama setiap menit (OTEL_METRICS_EXPORTER=none menonaktifkannya). OTEL_TRACES_SAMPLER_ARG mengatur proporsi trace yang disimpan. Log dikirim ke keluaran standar pada LOG_LEVEL, dan dirotasi oleh Compose. Trace tidak pernah memuat data pribadi.

Egress wilayah (residensi data UE)

QUIRE_REGION=eu menyatakan bahwa tumpukan melayani organisasi Uni Eropa. Worker kemudian membatasi setiap permintaan keluar untuk organisasi yang dipasangi wilayah UE ke daftar izin (21-compliance.md bagian 8.1). Daftar itu mencakup host yang dinyatakan oleh layanan terkonfigurasi untuk wilayah tersebut (endpoint penyimpanan, penyedia email, penyedia video terhosting, target penyimpanan milik organisasi, penyedia AI, dan akun email), host layanan yang memiliki derogasi aktif, serta host yang Anda cantumkan di QUIRE_EGRESS_ALLOW_HOSTS. Permintaan ke host publik lain ditolak sebelum dikirim, penolakan dicatat di jejak audit organisasi sebagai privacy/egress_refused, dan ditampilkan di Kepatuhan, Residensi data.

Organisasi UK dan US tidak dibatasi daftar host; pemeriksaan wilayah layanan tetap berlaku. Setel daftar tersebut pada worker; halaman admin membacanya di tingkat web untuk menampilkan daftar izin, jadi letakkan di docker/.env yang dibaca oleh setiap layanan.

Pemeriksaan aplikasi memberikan kesalahan yang jelas dan entri audit, tetapi bukan jaminannya: kode bisa saja salah. Jaminannya adalah jaringan. Compose tidak menegakkannya untuk Anda. Untuk tumpukan regional, tempatkan layanan worker dan web di jaringan internal: true yang satu-satunya rute keluarnya adalah proxy egress (misalnya Squid atau kontainer tinyproxy) yang mengizinkan host yang sama dengan QUIRE_EGRESS_ALLOW_HOSTS, ditambah host layanan yang Anda konfigurasikan, lalu setel HTTPS_PROXY untuk layanan tersebut. Halaman residensi mencantumkan host persis yang diizinkan aplikasi, sehingga kedua daftar dapat dibandingkan.

Kesehatan

docker compose -f docker/compose.yaml ps menampilkan status kesehatan setiap layanan.

TLS

Layanan proxy (Caddy, Apache-2.0, docker/caddy/Caddyfile) merupakan bagian dari tumpukan bawaan. Layanan ini merespons pada port 80 dan 443 serta mengarahkan:

init-env.sh menurunkan QUIRE_PROXY_APP_HOST, QUIRE_PROXY_CONTENT_HOST, QUIRE_PROXY_HTTPS_PORT, QUIRE_COLLAB_URL, dan IMGPROXY_URL dari kedua origin agar nilainya selalu selaras. Jika Anda mengubah origin secara manual, ubah semua pengaturan terkait secara bersamaan.

Sertifikat mengikuti QUIRE_PROXY_TLS:

• internal (nilai bawaan): otoritas sertifikat milik Caddy untuk localhost, *.localhost, dan lvh.me. Percayai sertifikat akarnya sekali, lalu buka:

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

  Tambahkan quire-local-ca.crt ke penyimpanan sertifikat tepercaya sistem atau browser. Untuk curl, berikan dengan --cacert.

• Alamat email: sertifikat ACME otomatis (Let’s Encrypt, lalu ZeroSSL) untuk nama host sungguhan. DNS kedua origin dan setiap host penyewa harus mengarah ke sini, dan port 80 serta 443 harus dapat dijangkau dari internet.

Sertifikat host penyewa diterbitkan sesuai permintaan, pada kunjungan pertama, dan hanya setelah web mengonfirmasi nama tersebut milik instalasi ini (/tls-allowed, diminta melalui jaringan Compose). Sertifikat wildcard dan plugin penyedia DNS tidak diperlukan, dan orang asing yang mengarahkan nama ke host ini tidak dapat memaksanya meminta sertifikat. Sertifikat dan otoritas lokal berada di volume caddy-data; jika Anda menggunakan internal, cadangkan bersama data lainnya.

Web hanya memercayai X-Forwarded-For dari proxy: proxy memiliki alamat tetap (QUIRE_PROXY_ADDRESS, bawaan 172.29.64.10) pada subnet tetap (QUIRE_COMPOSE_SUBNET), dan QUIRE_TRUSTED_PROXY_CIDRS mencantumkan alamat tersebut. Jika subnet berbenturan dengan jaringan di host, ubah keduanya dan jalankan docker compose down sebelum up.

Di balik reverse proxy Anda sendiri

Untuk menggunakan load balancer atau proxy yang sudah Anda jalankan, jangan sertakan proxy (docker compose up -d --scale proxy=0) dan akhiri TLS di depan web (8080), content (8081), collab (1234, WebSocket), dan centrifugo (8000, WebSocket). Setel alamat publik di QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, serta QUIRE_COLLAB_URL (wss://), dan rentang alamat proxy Anda di QUIRE_TRUSTED_PROXY_CIDRS.

Pemecahan masalah

• init keluar dengan pesan “QUIRE_DATABASE_ID is not a UUID”: setel dengan uuidgen.
• web dimulai ulang dengan pesan “did not start on compose”: log mencantumkan setiap pengaturan yang tidak dapat dipenuhi dan nilai penggantinya.
• Mengubah kata sandi peran di .env setelah permulaan pertama tidak berdampak: skrip init hanya berjalan sekali. Gunakan ALTER ROLE.
• Unggahan gagal dengan kesalahan pemindaian saat CLAMAV_URL disetel: ClamAV mengunduh tanda tangannya pada permulaan pertama, dan proses ini memerlukan beberapa menit.