Panduan operasional sehari-hari Sudirman Voice untuk lingkungan lokal, tes, dev, dan production, termasuk konfigurasi variabel lingkungan, deploy otomatis VPS, pencadangan & pemulihan bencana, serta troubleshooting. Detail setup awal data Serdik dan proteksi branch ada di README.
URL koneksi PostgreSQL pooled (-pooler) untuk runtime aplikasi (src/lib/db.ts)
DATABASE_URL_UNPOOLED
Ya
URL koneksi direct (tanpa -pooler) untuk Prisma CLI (prisma.config.ts), setup.ts, dan pg_dump
APP_ENV
Di VPS
Isi production atau dev. Saat production, Mode Uji dan seluruh script seed ditolak mutlak
DEV_LOGIN
Opsional (Dev/Lokal)
Isi true untuk mengaktifkan penukar akun di header. Jangan pernah disetel di Production
PRODUCTION_DB_HOST
Opsional (Dev)
Host pooler DB production; pengaman tambahan agar Mode Uji di dev mati otomatis jika tersambung ke DB production
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
Wajib di Prod
Kredensial OAuth 2.0 Web untuk /aktivasi lewat akun Google (tanpa keduanya, aktivasi tetap berjalan lewat kode email jika SMTP aktif, atau PIN dari Admin)
URL dasar publik tanpa / di akhir untuk tautan & logo email (https://voice.p3mdi.id / https://voice-dev.p3mdi.id)
CRON_SECRET
Ya jika cron aktif
Token acak >= 24 karakter; dikirim cron sebagai Authorization: Bearer <nilai> (dicek via timingSafeEqual)
EMAIL_IZINKAN
Hanya Dev
Daftar alamat atau domain penerima yang diizinkan dipisah koma (a@gmail.com, @p3mdi.id). Alamat lain ditolak sebelum menyentuh SMTP. Jangan diisi di Production
EMAIL_PER_PUTARAN, EMAIL_ANGGARAN_MS
Opsional
Jumlah email per eksekusi cron (bawaan 10) dan batas waktu per putaran (bawaan 20000 ms)
2.3 Variabel Khusus VPS (docker-compose.yml) & Testing/Seed
Gunakan layanan cron eksternal (mis. cron-job.org) secara terpisah untuk Dev dan Production, dengan header Authorization: Bearer <CRON_SECRET> dan batas timeout HTTP 30 detik:
Rute
Jadwal
Fungsi & Respons JSON
/api/cron/pengingat
Tiap 10–15 menit
Mengirim pengingat bertahap 6, 3, dan 1 jam sebelum tenggat untuk form dan polling wajib yang belum diisi. Respons: { ok: true, terkirim }
/api/cron/email
Tiap 10 menit
Mengantrekan ringkasan harian sekali setelah 07.00 WIB (pg_advisory_xact_lock), lalu memproses antrean email_keluar. Respons: { ok: true, ringkasanDiantre, terkirim, gagal, sisa, dilewati?, tertahan?, galat? }
SPF: v=spf1 include:_spf.mail.hostinger.com ~all (gabungkan bila sudah ada record SPF)
DKIM: Aktifkan record DKIM dari menu Email Hostinger
DMARC: Record _dmarc bernilai v=DMARC1; p=none; rua=mailto:notifications@p3mdi.id
Verifikasi lewat fitur Show original di Gmail agar SPF, DKIM, dan DMARC ketiganya berstatus PASS.
Aktivasi dan lupa PIN (/aktivasi) mencocokkan alamat email Google terverifikasi dengan email yang dicatat Admin untuk akun tersebut (alamat P3MDI atau pribadi):
Di Google Cloud Console, buat proyek dan layar persetujuan OAuth bertipe External, scope openid dan email, lalu ubah status ke Published (mode Testing hanya berlaku 7 hari dan maksimal 100 pengguna).
Buat OAuth Client ID tipe Web. Daftarkan Authorized redirect URIs: https://voice.p3mdi.id/api/auth/google/callback, https://voice-dev.p3mdi.id/api/auth/google/callback, dan http://localhost:3000/api/auth/google/callback.
Isi GOOGLE_CLIENT_ID dan GOOGLE_CLIENT_SECRET di .env VPS. Alamat callback dibentuk otomatis dari header x-forwarded-host / x-forwarded-proto sehingga host harus persis sama dengan yang terdaftar.
Server berjalan di VPS Hostinger (Ubuntu 24.04) bersama aplikasi lain. Coolify tidak dipakai. Port 80/443 dipegang oleh Traefik milik coolify-proxy; docker-compose.yml hanya mendaftarkan container pada jaringan eksternal coolify tanpa mempublikasikan port ke host.
Direktori & Akun: User Linux sudirman (grup docker), folder ~/sudirman-voice-dev (branch dev) dan ~/sudirman-voice-prod (branch main), dengan berkas .env berizin 0600.
app (target runner): Hanya berjalan setelah migrate selesai sukses (service_completed_successfully). Berjalan sebagai user non-root node, batas memori 1g, rotasi log json-file (max-size: 10m, max-file: 3), dan HEALTHCHECK setiap 30 detik ke http://127.0.0.1:3000/api/sehat.
Deploy Otomatis (scripts/deploy-vps.sh):
GitHub Actions melakukan SSH ke sudirman@$VPS_HOST dengan kunci deploy yang dibatasi di authorized_keys (command="/home/sudirman/bin/deploy-sudirman-voice",restrict). Skrip dilindungi flock per lingkungan (maks. tunggu 30 menit) dan menjalankan urutan:
git fetch & verifikasi bahwa commit target adalah ancestor branch (dev atau main).
Tag image aktif saat ini menjadi <proj>-app:sebelum sebagai titik rollback.
docker compose build --quiet — jika gagal, kode di-reset ke commit sebelumnya dan container lama tetap melayani trafik tanpa downtime.
docker compose up -d — menjalankan migrate lalu menyalakan container app baru.
Polling status healthy hingga 40 kali (jeda 3 detik = 120 detik). Rollback Otomatis: jika container baru tidak sehat, skrip otomatis mencetak log terakhir, memulihkan tag :sebelum ke image utama, mengembalikan kode git, menyalakan ulang container lama (--no-build --no-deps app), dan keluar dengan kode galat 1.
Membersihkan image lama milik proyek ini (docker image prune -f --filter "label=com.docker.compose.project=$PROJ").
Deploy Manual (Cadangan) & Pembaruan Skrip:
Deploy manual: cd ~/sudirman-voice-prod && git pull && docker compose up -d --build
Bila scripts/deploy-vps.sh berubah, salin ulang di VPS: install -m 700 scripts/deploy-vps.sh ~/bin/deploy-sudirman-voice
VPS dilengkapi swap 4 GB (/swapfile, vm.swappiness=10) untuk menjaga stabilitas saat docker compose build.
Pastikan variabel .env Production lengkap (DATABASE_URL, DATABASE_URL_UNPOOLED, APP_ENV=production, Google OAuth, VAPID, SMTP, EMAIL_FROM, APP_URL, CRON_SECRET); pastikan DEV_LOGIN dan EMAIL_IZINKANtidak ada.
Pastikan ketiga job CI (check, integration, e2e) hijau di PR sebelum merge ke main.
Untuk rilis versi baru: perbarui CHANGELOG.md, docs/enhancement-log.md, naikkan versi via npm version X.Y.Z --no-git-tag-version, merge dev → main, dan buat tag git tag -a vX.Y.Z -m "vX.Y.Z".
Setelah deploy selesai: verifikasi /api/sehat, uji aktivasi akun, uji kirim & baca /admin/laporan, impor data email Serdik bila ada akun baru, dan jalankan uji panggil kedua rute cron (pastikan respons 200 dengan "ok":true).
Neon Point-in-Time Recovery (PITR) & Branching: Database production berjalan di Neon organisasi. Sebelum migrasi berisiko tinggi atau operasi data massal, buat branch atau snapshot Neon sebagai titik pemulihan cepat.
Backup Logis Manual (pg_dump): Selalu gunakan URL DATABASE_URL_UNPOOLED (tanpa -pooler dan tanpa perintah pengubah sesi di host pooler!):
Otomatis: scripts/deploy-vps.sh otomatis kembali ke <proj>-app:sebelum bila container baru gagal healthy dalam 120 detik.
Manual (bila bug fungsional ditemukan setelah container sempat sehat):
Terminal window
cd~/sudirman-voice-prod
gitlog-n5--oneline
gitreset--hard<commit-sebelumnya>
dockercomposeup-d--buildapp
Rollback Migrasi / Restore Database:
Prisma migrate deploy tidak menjalankan skrip down otomatis. Apabila perubahan skema merusak data, pulihkan melalui fitur Branch Restore / PITR di konsol Neon atau gunakan pg_restore ke database baru lewat URL unpooled lalu arahkan ulang .env (DATABASE_URL & DATABASE_URL_UNPOOLED) dan restart docker compose up -d app.
Seed Data Dev/Lokal (prisma/seed.ts): Menjalankan npx prisma db seed membuat 20 Serdik dasar (001 Admin, 002 Lemusdik, 003 Seksi Riset, PIN 482915), contoh aspirasi, seed-form.ts (6 form), seed-polling.ts (2 polling), seed-hackathon.ts (5 hackathon di semua tahap), dan seed-demo.ts (Serdik 021–060, form/polling/aspirasi tambahan, serta akun showcase 090–092).
Sifat Seed: Seluruh seed bersifat create-only, menolak host non-lokal tanpa SEED_ALLOW_REMOTE=true, dan menolak mutlak bila APP_ENV=production atau VERCEL_ENV=production.
Penyimpanan Media: Foto aspirasi/bukti, banner form, dan tangkapan layar hackathon disimpan di PostgreSQL (bytea). Kuota Neon 0,5 GB cukup untuk sekitar 1.000–2.500 foto (lihat kapasitas rinci di data-model.md).
Gagal koneksi DB, migrasi belum sukses, atau port bentrok
Jalankan cd ~/sudirman-voice-prod && docker compose ps lalu docker compose logs app --tail 100 dan docker compose logs migrate --tail 50. Cek endpoint internal dengan docker compose exec app node -e "fetch('http://127.0.0.1:3000/api/sehat').then(r=>console.log(r.status))".
Galat SQL relation "<nama_tabel>" does not exist
Query mentah lupa prefix public. pada DB dengan search_path kosong
Pastikan di production DB sudah disetel ALTER DATABASE voice SET search_path TO public, dan perbaiki SQL mentah di kode agar memakai public.<tabel>.
Login Google gagal (redirect_uri_mismatch)
Domain/protokol dari x-forwarded-host/x-forwarded-proto tidak cocok dengan Google Console
Periksa header yang diteruskan Traefik, pastikan https://<domain>/api/auth/google/callback terdaftar persis di Google Cloud Console, dan periksa GOOGLE_CLIENT_ID di .env.
Notifikasi email tertahan (tertahan: true)
Hostinger SMTP membalas 421/451/452 (rate limit)
Normal: antrean otomatis dijeda 30 menit (cobaPada) tanpa menghabiskan jatah percobaan. Jika ada baris berstatus GAGAL, periksa kolom galat di tabel email_keluar. Di dev, cek apakah penerima terhalang EMAIL_IZINKAN.
Web Push gagal di perangkat baru atau setelah ganti kunci
NEXT_PUBLIC_VAPID_PUBLIC_KEY diubah tanpa rebuild image Docker
Variabel NEXT_PUBLIC_* ditanam saat docker build. Lakukan docker compose build --no-cache app && docker compose up -d app.
Cron mengembalikan 401 tidak berwenang
CRON_SECRET di .env VPS tidak sama dengan header layanan cron atau panjang < 24 karakter
Pastikan panjang CRON_SECRET >= 24 karakter dan header persis Authorization: Bearer <nilai>.
Mode uji tidak muncul di dev
APP_ENV=production, DEV_LOGIN tidak true, atau DATABASE_URL menunjuk ke PRODUCTION_DB_HOST
Periksa APP_ENV=dev, DEV_LOGIN=true, dan pastikan DB yang dituju benar-benar branch dev.