Portal SPMB adalah aplikasi web milik Yayasan Penyelenggaraan Ilahi Indonesia (YPII) yang dipakai orang tua/wali calon siswa untuk memantau dan menindaklanjuti proses SPMB (Seleksi Penerimaan Murid Baru) anaknya. Portal SPMB dijalankan sebagai satu stack Docker Compose bernama spmb-portal-ypii yang berisi dua layanan: aplikasi web (Next.js) yang menjadi satu-satunya layanan terbuka ke publik melalui reverse proxy Traefik, dan layanan backend (FastAPI) yang hanya dapat dihubungi dari dalam jaringan stack.
Portal SPMB tidak memiliki basis data sendiri. Seluruh data pendaftaran dibaca dari dan ditulis kembali ke Odoo YPII melalui REST API muk_rest, sehingga stack ini tidak memiliki volume penyimpanan maupun prosedur cadangan data. Satu deployment melayani satu instance Odoo; enam unit sekolah Kebon Dalem berada di dalam instance Odoo yang sama sebagai Operating Unit, bukan sebagai deployment terpisah.
Instruksi Kerja Mengonfigurasi Deployment Portal SPMB bertujuan memastikan administrator sistem dapat menyiapkan satu deployment Portal SPMB yang benar-benar dapat diakses orang tua/wali pada domain yang ditetapkan, terhubung ke instance Odoo YPII yang benar, dan mampu menerbitkan sesi masuk beserta kode OTP (One-Time Password) tanpa kegagalan konfigurasi.
Sebelum menjalankan Instruksi Kerja Mengonfigurasi Deployment Portal SPMB, seluruh butir berikut sudah terpenuhi.
traefik-public sudah tersedia.odoo14-cantum-ypii_default sudah tersedia. Jaringan ini dipakai layanan backend Portal SPMB semata untuk menemukan alamat container Odoo YPII.muk_rest di Odoo YPII sudah dibuat, dan pasangan client id beserta client secret-nya sudah tersedia.ir.mail_server) sudah dikonfigurasi dan berfungsi mengirim email. Portal SPMB tidak memiliki SMTP sendiri — kode OTP dikirim melalui mail server Odoo YPII.docker login ghcr.io sudah dijalankan pada server ini.cakrawala-tumbuh/spmb-portal-ypii pada server tersebut..env.openssl, untuk membuat kunci sesi.spmb-portal-ypii pada server.make setup. Perintah ini menyalin berkas contoh .env.example menjadi berkas .env bila .env belum ada, dan tidak menimpa .env yang sudah ada..env dengan editor teks. Seluruh langkah berikutnya mengubah berkas ini.Berkas
.envmemuat nilai rahasia dan sengaja tidak ikut tersimpan di repositori. Jangan menyalin isinya ke tiket, pesan, atau dokumen mana pun.
SPMB_WEB_HOST dengan nama domain publik deployment ini, misalnya spmb-portal.ypiigroup.or.id. Variabel ini wajib diisi.Nilai SPMB_WEB_HOST dipakai pada dua tempat sekaligus: sebagai aturan Host pada router Traefik milik layanan aplikasi web, dan sebagai nilai NEXT_PUBLIC_API_BASE_URL aplikasi web. Bila variabel ini kosong, Docker Compose menolak menjalankan stack dengan pesan web host required.
Hanya layanan aplikasi web yang memiliki router Traefik. Layanan backend sengaja dibiarkan tanpa router dan tanpa keanggotaan jaringan
traefik-public, sehingga backend tidak dapat dihubungi dari internet. Jangan menambahkan label Traefik pada layanan backend.
ODOO_BASE_URL dengan alamat instance Odoo YPII, misalnya https://odoo.ypiigroup.or.id.ODOO_DB dengan nama database Odoo YPII, misalnya ypii_prod.ODOO_CLIENT_ID dengan client id aplikasi OAuth2 muk_rest, misalnya spmb-portal.ODOO_CLIENT_SECRET dengan client secret aplikasi OAuth2 muk_rest. Nilai ini bersifat rahasia.ODOO_REQUEST_TIMEOUT_SECONDS pada nilai bawaan 15.0 kecuali ada alasan khusus mengubahnya.Bila
ODOO_CLIENT_SECRETkosong atau salah, layanan backend tidak berhenti dan container tetap tampak sehat. Kegagalannya hanya terlihat sebagai portal yang tidak dapat memuat data pendaftaran, dan sebagai jawaban503pada pemeriksaan kesiapanGET /api/v1/ready. Selalu periksa kesiapan setelah mengubah keempat variabel ini, jangan hanya melihat status container.
openssl rand -hex 48.JWT_SECRET dengan nilai acak tersebut. Variabel ini wajib diisi di lingkungan produksi.JWT_ALGORITHM pada nilai bawaan HS256.ACCESS_TOKEN_TTL_SECONDS (nilai bawaan 900, setara 15 menit) dan REFRESH_TOKEN_TTL_SECONDS (nilai bawaan 2592000, setara 30 hari) sesuai kebutuhan masa berlaku sesi.Bila
JWT_SECRETkosong, layanan backend menolak menerbitkan sesi: permintaan verifikasi kode OTP dijawab503alih-alih menerbitkan token yang tidak aman. Akibatnya tidak seorang pun dapat masuk ke Portal SPMB, walaupun kode OTP tetap terkirim ke email.
Jangan mengubah
JWT_SECRETpada deployment yang sudah berjalan. Mengubahnya membatalkan seluruh sesi dan token penyegar yang sedang beredar sekaligus, sehingga semua orang tua/wali yang sedang masuk terlempar ke halaman masuk dan harus meminta kode OTP baru.
OTP_LENGTH (nilai bawaan 6) sebagai jumlah digit kode OTP.OTP_TTL_SECONDS (nilai bawaan 300, setara 5 menit) sebagai masa berlaku satu kode OTP.OTP_MAX_ATTEMPTS (nilai bawaan 5) sebagai batas percobaan memasukkan kode sebelum kode dianggap hangus.OTP_RESEND_COOLDOWN_SECONDS (nilai bawaan 60) sebagai jeda minimum antar permintaan kirim ulang kode.OTP_EMAIL_FROM dengan identitas pengirim email yang pantas, misalnya Portal SPMB Kebon Dalem <noreply@ypiigroup.or.id>.Bila
OTP_EMAIL_FROMdibiarkan kosong, email kode OTP terkirim atas nama pengirim bawaan mail server Odoo YPII — pada umumnya tampil sebagai "Administrator". Isi variabel ini sebelum portal dibuka untuk orang tua/wali.
Rincian perilaku penerbitan dan pengiriman kode OTP dijelaskan pada Portal SPMB — Penerbitan dan Pengiriman Kode OTP Masuk lewat Mail Server Odoo YPII.
CAPTCHA_ENABLED bernilai false dan biarkan HCAPTCHA_SECRET, HCAPTCHA_SITE_KEY, serta NEXT_PUBLIC_HCAPTCHA_SITE_KEY kosong.CAPTCHA_ENABLED dengan true, isi HCAPTCHA_SECRET dengan secret hCaptcha (bersifat rahasia), dan isi NEXT_PUBLIC_HCAPTCHA_SITE_KEY dengan site key hCaptcha. Variabel NEXT_PUBLIC_HCAPTCHA_SITE_KEY memang bersifat publik dan dirender pada halaman masuk.HCAPTCHA_SITE_KEY bila pemeriksaan kesiapan backend perlu ikut melaporkan status konfigurasi captcha.HCAPTCHA_VERIFY_URL dan HCAPTCHA_TIMEOUT_SECONDS pada nilai bawaannya.Kedua sisi captcha harus konsisten. Bila
CAPTCHA_ENABLEDbernilaitruesementaraNEXT_PUBLIC_HCAPTCHA_SITE_KEYkosong, halaman masuk tidak menampilkan widget captcha sehingga permintaan kode OTP tidak pernah menyertakan jawaban captcha — tidak seorang pun dapat masuk ke Portal SPMB. Verifikasi captcha juga bersifat fail-closed: bila layanan hCaptcha tidak terjangkau atau kehabisan waktu, verifikasi dianggap gagal, bukan lolos.
APP_TITLE dengan judul aplikasi, misalnya Portal Orang Tua YPII.SCHOOL_NAME dengan nama penyelenggara, misalnya Yayasan Penyelenggaraan Ilahi Indonesia.SCHOOL_LOGO_URL dengan alamat berkas logo bila tersedia.THEME_PRIMARY, THEME_SECONDARY, dan THEME_ACCENT dengan kode warna heksadesimal merek. Palet YPII yang dipakai deployment Semarang adalah #9d0a0e untuk warna primer serta #daefb3 untuk warna sekunder dan aksen.TZ (nilai bawaan Asia/Jakarta) dan LOG_LEVEL (nilai bawaan INFO).Pada rilis aplikasi web v0.21.0, kelima variabel merek (
SCHOOL_NAME,SCHOOL_LOGO_URL,THEME_PRIMARY,THEME_SECONDARY,THEME_ACCENT) disajikan layanan backend melaluiGET /api/v1/branding, tetapi belum dibaca oleh aplikasi web. Mengubah nilainya belum mengubah tampilan Portal SPMB yang dilihat orang tua/wali. Tema warna yang tampil saat ini adalah pilihan pengguna sendiri yang tersimpan di peramban masing-masing, bukan hasil konfigurasi deployment.
SPMB_BACKEND_VERSION dan SPMB_WEB_VERSION dengan tag versi image yang akan dijalankan, misalnya v0.17.0 untuk backend dan v0.21.0 untuk aplikasi web. Nilai bawaan keduanya adalah latest.DOCS_ENABLED bernilai true. Dokumentasi API hanya terjangkau dari dalam jaringan stack karena layanan backend tidak terbuka ke publik.Menyematkan tag versi (
vX.Y.Z) alih-alihlatestmembuat deployment dapat diulang dengan hasil yang sama dan membuat pembaruan versi menjadi tindakan yang disengaja. Prosedur menaikkan versi dijelaskan pada Menjalankan, Memantau, dan Menaikkan Versi Stack Portal SPMB.
.env.make pull untuk menarik image sesuai tag yang ditetapkan pada Langkah 8.make up untuk menjalankan stack.Setiap kali berkas
.envdiubah, terapkan perubahannya denganmake up, bukan denganmake restart. Perintahmake restarthanya menjalankan ulang container yang sudah ada, sehingga variabel lingkungan yang baru tidak terbaca — nilai lama tetap berlaku dan perubahan konfigurasi tampak seolah tidak berpengaruh. Perintahmake upmembentuk ulang container yang konfigurasinya berubah, sehingga nilai baru benar-benar diterapkan.
Jalankan make ps dan tunggu sampai kedua layanan berstatus sehat (healthy). Layanan aplikasi web baru dijalankan setelah layanan backend dinyatakan sehat.
Periksa kesiapan layanan backend dari dalam jaringan stack:
docker compose exec spmb-portal-backend python - <<'PY'
import urllib.error, urllib.request
try:
resp = urllib.request.urlopen("http://127.0.0.1:8000/api/v1/ready", timeout=5)
print(resp.status, resp.read().decode())
except urllib.error.HTTPError as exc:
print(exc.code, exc.read().decode())
PY
Jawaban 200 menandakan koneksi Odoo YPII, mail server, dan konfigurasi captcha sudah lengkap. Jawaban 503 menandakan salah satu di antaranya belum benar.
Buka alamat https:// diikuti nilai SPMB_WEB_HOST pada peramban. Halaman masuk Portal SPMB harus tampil melalui HTTPS, dan alamat http:// harus dialihkan otomatis ke https://.
Lakukan satu percobaan masuk memakai alamat email yang sudah tercatat di Odoo YPII sebagai email kontak pemilik minimal satu pendaftaran calon siswa yang masih aktif. Kode OTP harus tiba di kotak masuk email tersebut, dan memasukkan kode itu harus membawa ke halaman Beranda Portal SPMB.
spmb-portal-ypii berjalan dan berstatus sehat pada keluaran make ps.GET /api/v1/ready pada layanan backend menjawab 200.SPMB_WEB_HOST, dan akses melalui HTTP dialihkan otomatis ke HTTPS.| Masalah | Penyebab | Penanganan |
|---|---|---|
Docker Compose menolak menjalankan stack dengan pesan web host required |
Variabel SPMB_WEB_HOST kosong di berkas .env |
Isi SPMB_WEB_HOST sesuai Langkah 2, lalu jalankan ulang make up |
| Domain Portal SPMB tidak dapat dibuka, atau sertifikat TLS tidak pernah terbit | Catatan DNS domain belum mengarah ke server ini, atau stack Traefik belum berjalan | Pastikan catatan DNS A/AAAA sudah benar dan stack Traefik sudah dijalankan lebih dulu, lalu jalankan ulang make up |
Container berstatus sehat tetapi portal tidak dapat memuat data pendaftaran; GET /api/v1/ready menjawab 503 |
Salah satu dari ODOO_BASE_URL, ODOO_DB, ODOO_CLIENT_ID, atau ODOO_CLIENT_SECRET kosong atau salah |
Perbaiki keempat variabel sesuai Langkah 3, lalu jalankan make up agar container dibentuk ulang, dan ulangi pemeriksaan kesiapan |
| Layanan backend tidak dapat menghubungi Odoo YPII walau alamat sudah benar | Stack Odoo YPII belum berjalan, sehingga jaringan odoo14-cantum-ypii_default tidak tersedia |
Jalankan stack Odoo YPII lebih dulu, lalu jalankan ulang make up |
| Kode OTP tiba di email, tetapi memasukkan kode berakhir dengan kegagalan layanan | JWT_SECRET kosong sehingga penerbitan sesi ditolak dengan 503 |
Isi JWT_SECRET sesuai Langkah 4, lalu jalankan make up agar container dibentuk ulang |
| Seluruh orang tua/wali tiba-tiba terlempar ke halaman masuk setelah pemeliharaan | Nilai JWT_SECRET diubah pada deployment yang sudah berjalan |
Kembalikan nilai JWT_SECRET semula bila masih tersimpan; bila tidak, sampaikan kepada Bidang PPDB YPII bahwa seluruh pengguna perlu meminta kode OTP baru |
| Tidak seorang pun dapat meminta kode OTP walau email sudah benar | CAPTCHA_ENABLED bernilai true sementara NEXT_PUBLIC_HCAPTCHA_SITE_KEY kosong |
Isi NEXT_PUBLIC_HCAPTCHA_SITE_KEY, atau kembalikan CAPTCHA_ENABLED ke false sesuai Langkah 6, lalu jalankan make up agar container dibentuk ulang |
| Permintaan kode OTP gagal hanya pada sebagian waktu | Layanan hCaptcha tidak terjangkau atau kehabisan waktu; verifikasi bersifat fail-closed sehingga dianggap gagal | Periksa keterjangkauan https://api.hcaptcha.com dari server; bila gangguan berlanjut, nonaktifkan captcha sementara sesuai Langkah 6 |
| Email kode OTP tampil dikirim oleh "Administrator" | OTP_EMAIL_FROM masih kosong |
Isi OTP_EMAIL_FROM sesuai Langkah 5, lalu jalankan make up agar container dibentuk ulang |
| Kode OTP tidak pernah tiba di email mana pun | Mail server Odoo YPII (ir.mail_server) belum dikonfigurasi atau sedang gagal mengirim |
Perbaiki konfigurasi mail server di Odoo YPII; Portal SPMB tidak memiliki SMTP sendiri sehingga tidak ada yang dapat diperbaiki dari sisi stack ini |
| Warna dan nama sekolah pada portal tidak berubah walau variabel merek sudah diisi | Aplikasi web v0.21.0 belum membaca GET /api/v1/branding |
Tidak ada penanganan dari sisi konfigurasi; perubahan tampilan menunggu rilis aplikasi web yang membaca endpoint tersebut |