Skip to content

Operasional: Lingkungan, Deploy, Backup & Runbook (SV-OPS-001)

Field Nilai
ID Dokumen SV-OPS-001
Pilar Rekayasa Perangkat Lunak
Standar Acuan ISO/IEC/IEEE 26514 / Site Reliability Engineering (SRE)
Status Aktif / Tersinkronisasi dengan Kode
Terakhir Diperbarui 2026-11-21
Sumber Kebenaran .env.example, .env.test, docker-compose.yml, Dockerfile, prisma.config.ts, scripts/deploy-vps.sh, scripts/setup.ts, scripts/test-db.sh, .github/workflows/ci.yml, src/app/api/cron/*, src/app/api/sehat/route.ts

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.

Lingkungan Branch Database Alamat & Catatan
Lokal Bebas Postgres lokal (5432) .env disalin dari .env.example
Tes — Postgres port 5433 (sv_test, npm run db:test:up) .env.test, search_path = '', direset tiap tes integrasi
Dev dev Neon proyek lama, branch dev VPS (https://voice-dev.p3mdi.id). DEV_LOGIN=true boleh (Mode uji)
Production main Neon organisasi, database voice VPS (https://voice.p3mdi.id). APP_ENV=production; mutlak tanpa DEV_LOGIN, tanpa EMAIL_IZINKAN, tanpa seed

Vercel tidak lagi dipakai sejak versi 1.2.0.

2. Daftar Lengkap Variabel Lingkungan (.env.example & .env.test)

Section titled “2. Daftar Lengkap Variabel Lingkungan (.env.example & .env.test)”
Variabel Wajib Keterangan
DATABASE_URL Ya 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)
Variabel Wajib Keterangan
NEXT_PUBLIC_VAPID_PUBLIC_KEY Opsional Kunci publik Web Push (npx web-push generate-vapid-keys). Ditanam saat build image Docker (ARG): mengubah nilainya membutuhkan build ulang
VAPID_PRIVATE_KEY, VAPID_SUBJECT Opsional Kunci privat VAPID & subjek (mis. mailto:notifications@p3mdi.id). Jika kosong, Web Push nonaktif tanpa galat
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS Opsional Konfigurasi SMTP Hostinger (smtp.hostinger.com, 465, notifications@p3mdi.id, password mailbox)
EMAIL_FROM Opsional Pengirim email, mis. "Sudirman Voice <notifications@p3mdi.id>"
APP_URL Ya di VPS 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

Section titled “2.3 Variabel Khusus VPS (docker-compose.yml) & Testing/Seed”
Variabel Lingkungan Keterangan
COMPOSE_PROJECT_NAME VPS Nama proyek Docker Compose sekaligus nama router Traefik (sudirman-voice-dev / sudirman-voice-prod)
APP_DOMAIN VPS Domain router Traefik (voice-dev.p3mdi.id / voice.p3mdi.id)
TRAEFIK_NETWORK, TRAEFIK_ENTRYPOINT_HTTP, TRAEFIK_ENTRYPOINT_HTTPS, TRAEFIK_CERTRESOLVER VPS Jaringan & router Traefik bawaan VPS (default: coolify, http, https, letsencrypt)
SEED_ALLOW_REMOTE Hanya Dev Harus true jika menjalankan prisma db seed ke DB dev jarak jauh. Ditolak di Production
PW_CHROMIUM_PATH Opsional (Lokal) Path ke binary Chrome/Chromium lokal jika browser Playwright belum diunduh

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? }

Untuk mencegah email masuk folder spam:

  • 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):

  1. 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).
  2. 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.
  3. 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.
  • Arsitektur Container (docker-compose.yml & Dockerfile):
    • migrate (target migrate): Menjalankan npx prisma migrate deploy lalu berhenti (restart: "no").
    • 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:
    1. git fetch & verifikasi bahwa commit target adalah ancestor branch (dev atau main).
    2. Tag image aktif saat ini menjadi <proj>-app:sebelum sebagai titik rollback.
    3. docker compose build --quiet — jika gagal, kode di-reset ke commit sebelumnya dan container lama tetap melayani trafik tanpa downtime.
    4. docker compose up -d — menjalankan migrate lalu menyalakan container app baru.
    5. 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.
    6. 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.
  1. 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_IZINKAN tidak ada.
  2. Pastikan ketiga job CI (check, integration, e2e) hijau di PR sebelum merge ke main.
  3. 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".
  4. 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).

6. Backup, Pemulihan Bencana (DR) & Rollback

Section titled “6. Backup, Pemulihan Bencana (DR) & Rollback”
  • 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!):
    Terminal window
    pg_dump "$DATABASE_URL_UNPOOLED" -Fc -f "backup-voice-$(date +%Y%m%d-%H%M).dump"

6.2 Prosedur Pemulihan (Restore) & Rollback

Section titled “6.2 Prosedur Pemulihan (Restore) & Rollback”
  • Rollback Kode / Container VPS:
    • 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
      git log -n 5 --oneline
      git reset --hard <commit-sebelumnya>
      docker compose up -d --build app
  • 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).
Gejala / Masalah Kemungkinan Penyebab Langkah Pemeriksaan & Solusi
Container app restart berulang / tidak healthy 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.