Skip to content

Panduan Deployment & Operasional Produksi — Soedirman Digital Repository (SDR)

Field Nilai
ID Dokumen SDR-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 .github/workflows/ci-deploy.yml, scripts/deploy-server.sh, Dockerfile, .env.example, lib/env.ts, prisma/seed.ts, scripts/media-cleanup.ts, scripts/repositories-purge.ts

Aplikasi Soedirman Digital Repository (SDR) dioperasikan sebagai kontainer Docker berbasis Node.js 24 (Dockerfile) yang dijalankan lewat docker compose di server produksi P3MDI (76.13.21.243) di balik reverse proxy HTTPS/TLS.

  • Portal Katalog & Pengajuan Publik: https://repo.p3mdi.id
  • Domain Pemendek Tautan (Shortlinks): https://go.p3mdi.id (diteruskan oleh proxy.ts ke /s/[alias])
  • Direktori Aplikasi Live di Server: /opt/soedirman-digital-repository (compose.yaml dan .env)
  • Direktori State CD & Rilis: /var/lib/sdr-cd (repository.git, releases/, deployments/, deployed-commit)
  • Skrip Deploy Server: /usr/local/sbin/sdr-deploy (disinkronkan dari scripts/deploy-server.sh)
flowchart TD
    DEV["Push ke branch master (GitHub)"] --> CI["GitHub Actions: Job verify (Ubuntu 24.04, Node 24)"]
    CI -->|"1. bash -n, db:validate, typecheck, lint, npm audit, Gitleaks, docker build"| HEAD["Cek HEAD master masih terbaru"]
    HEAD -->|"2. SSH + token GitHub via stdin"| CD["VPS Produksi (/usr/local/sbin/sdr-deploy)"]
    CD -->|"3. Fetch bare mirror + build image soedirman-digital-repository:SHA"| BK["4. Backup .env, tag :last-good, & pg_dump -Fc"]
    BK --> MIG["5. prisma migrate deploy"]
    MIG --> UP["6. Update SDR_RELEASE di .env & docker compose up -d app"]
    UP --> HLTH["7. Verifikasi internal 127.0.0.1:3000/api/health & HTTPS repo.p3mdi.id"]
    HLTH -->|"Sukses"| CLEAN["8. Simpan deployed-commit & pangkas rilis lama (simpan 3 terakhir + last-good)"]
    HLTH -->|"Gagal"| RB["Trap ERR: Pulihkan .env.bak & container sebelumnya"]

Image produksi dibangun menggunakan Dockerfile di root repositori:

  • Base Image: node:24-bookworm-slim dengan paket sistem ca-certificates dan openssl, berjalan di bawah user non-root node.
  • Argumen Build: ARG NEXT_PUBLIC_SITE_URL=https://repo.p3mdi.id disematkan ke environment build agar URL kanonik, sitemap, dan metadata Open Graph mengarah ke domain produksi.
  • Tahap Build:
    1. npm ci --no-audit --no-fund (dengan DATABASE_URL dummy saat tahap build)
    2. npx prisma generate
    3. ./node_modules/.bin/next build
  • Runtime Container: NODE_ENV=production, mengekspos port 3000, dan menjalankan ./node_modules/.bin/next start --hostname 0.0.0.0.

3. Pipeline CI/CD Otomatis (.github/workflows/ci-deploy.yml)

Section titled “3. Pipeline CI/CD Otomatis (.github/workflows/ci-deploy.yml)”

3.1 Job verify (Berjalan pada pull_request dan push ke master)

Section titled “3.1 Job verify (Berjalan pada pull_request dan push ke master)”
  1. Validasi sintaks skrip CD: bash -n scripts/deploy-server.sh.
  2. Instalasi bersih: npm ci --no-audit --no-fund.
  3. Generasi & validasi Prisma: npm run db:generate && npm run db:validate.
  4. Pemeriksaan tipe ketat: npm run typecheck.
  5. Linter (advisory): npm run lint (continue-on-error: true).
  6. Audit dependensi produksi: npm audit --omit=dev --audit-level=high.
  7. Pemindaian kebocoran rahasia pada riwayat Git: container ghcr.io/gitleaks/gitleaks:v8.24.2 (git --redact --log-opts=HEAD .).
  8. Uji build image produksi: docker build --build-arg NEXT_PUBLIC_SITE_URL=https://repo.p3mdi.id -t sdr-ci:${{ github.sha }} -f Dockerfile ..

3.2 Job deploy (Hanya pada push / workflow_dispatch di master)

Section titled “3.2 Job deploy (Hanya pada push / workflow_dispatch di master)”
  • Menggunakan grup konkurensi sdr-production (cancel-in-progress: false) agar proses deploy tidak tumpang tindih.
  • Memverifikasi bahwa commit GITHUB_SHA masih merupakan HEAD terbaru dari refs/heads/master lewat GitHub API (gh api).
  • Membuka koneksi SSH terotentikasi ke root@$DEPLOY_HOST menggunakan DEPLOY_SSH_KEY dan DEPLOY_KNOWN_HOSTS (dengan StrictHostKeyChecking=yes), mengirimkan ${{ github.token }} secara aman melalui stdin (tidak pernah ditulis permanen ke disk atau argumen CLI), serta mengeksekusi perintah deploy <40-char SHA>.

3.3 Tahapan Eksekusi scripts/deploy-server.sh di Server

Section titled “3.3 Tahapan Eksekusi scripts/deploy-server.sh di Server”
  1. Mengunci eksekusi dengan flock -w 900 pada /var/lock/sdr-deploy.lock.
  2. Memvalidasi argumen tepat berupa deploy <40-hex SHA> dan ketersediaan /opt/soedirman-digital-repository/.env serta compose.yaml.
  3. Mengambil pembaruan bare mirror /var/lib/sdr-cd/repository.git memakai header otorisasi token sementara dari stdin, lalu memastikan SHA target cocok dengan refs/remotes/origin/master.
  4. Memastikan sisa ruang disk pada /opt/soedirman-digital-repository minimal 2 GiB.
  5. Mengekstrak arsip commit ke /var/lib/sdr-cd/releases/<sha> dan membangun image soedirman-digital-repository:<sha>.
  6. Membuat direktori backup /var/lib/sdr-cd/deployments/<timestamp>-<sha>: menyalin .env (chmod 600), menandai image kontainer aktif sebelumnya sebagai soedirman-digital-repository:last-good, dan membuat dump database PostgreSQL terkompresi (pg_dump -U sdr -d sdr -Fc > database.dump).
  7. Menjalankan migrasi database: SDR_RELEASE=<sha> compose run --rm --no-deps -T app ./node_modules/.bin/prisma migrate deploy.
  8. Memperbarui nilai SDR_RELEASE=<sha> di .env secara atomik (mempertahankan hak akses 0600) menggunakan Python tempfile + os.replace.
  9. Menjalankan ulang layanan app: compose up -d --no-deps --wait --wait-timeout 120 app.
  10. Memverifikasi health check internal (http://127.0.0.1:3000/api/health) serta endpoint HTTPS publik ($site_url/api/health dan $site_url/repositories).
  11. Memperbarui skrip /usr/local/sbin/sdr-deploy, mencatat SHA di deployed-commit, dan membersihkan direktori rilis/image lama dengan menyimpan 3 rilis terakhir ditambah tag :last-good.

4. Katalog Variabel Lingkungan (.env.example & Runtime)

Section titled “4. Katalog Variabel Lingkungan (.env.example & Runtime)”

Seluruh konfigurasi disuntikkan lewat berkas .env (divalidasi oleh lib/env.ts). Jangan pernah menyertakan nilai rahasia asli ke repositori Git atau dokumentasi.

Variabel Lingkup Default / Contoh Aman Keterangan
DATABASE_URL Server postgresql://user:pass@host:5432/sdr?schema=public String koneksi PostgreSQL untuk Prisma 7 & migrasi
NEXT_PUBLIC_SITE_URL Publik / Build https://repo.p3mdi.id URL dasar portal publik, kanonik, OG, dan verifikasi deploy
AUTH_SECRET Server (dibangkitkan dengan openssl rand -base64 32) Kunci penandatanganan & enkripsi JWT Auth.js v5 (minimal 16–32 karakter)
AUTH_URL Server https://repo.p3mdi.id URL kanonik callback autentikasi Auth.js
SHORTLINK_HOSTNAME Server (proxy.ts) go.p3mdi.id Hostname yang memicu rewrite domain shortlink ke /s/[alias]
NEXT_PUBLIC_SHORTLINK_BASE_URL Publik / Admin UI go.p3mdi.id Domain dasar tampilan pada tabel & dialog admin /admin/shortlinks
NEXTAUTH_URL Server (proxy.ts) https://p3mdi.id Tujuan redirect saat pengunjung mengakses root / domain shortlink
ADMIN_SEED_NAME Seed Administrator SDR Nama akun Super Admin awal saat menjalankan prisma/seed.ts
ADMIN_SEED_USERNAME Seed / Script superadmin Username akun Super Admin awal (default superadmin)
ADMIN_SEED_EMAIL Seed admin@soedirman.ac.id Email opsional akun Super Admin awal
ADMIN_SEED_PASSWORD Seed / Script (wajib >= 12 karakter, simpan di vault server) Kata sandi awal saat seeding atau db:create-admin
ADMIN_SEED_RESET_PASSWORD Seed false Setel true hanya jika ingin mereset sandi admin awal lewat db:seed
SEED_DEMO_DATA Seed false (wajib false di produksi) Hanya dipakai di lokal/dev untuk membuat 3 karya demo
S3_ENDPOINT Server http://localhost:9000 (atau endpoint S3/R2) Endpoint Object Storage S3-kompatibel
S3_REGION Server us-east-1 Region bucket S3 / R2 (auto jika Cloudflare R2)
S3_BUCKET Server sdr-media Nama bucket penyimpanan gambar
S3_ACCESS_KEY_ID Server (disimpan di .env server) Access key ID Object Storage
S3_SECRET_ACCESS_KEY Server (disimpan di .env server) Secret access key Object Storage
S3_FORCE_PATH_STYLE Server true (MinIO) / false (AWS S3) Memaksa path-style addressing S3
S3_PUBLIC_BASE_URL Server https://media.p3mdi.id atau endpoint publik bucket Awalan URL publik gambar yang disimpan ke media_uploads.public_url
UPLOAD_MAX_BYTES Server 5242880 Batas ukuran maksimal unggahan per gambar dalam byte (5 MB)
LOGIN_MAX_ATTEMPTS Server 5 Referensi konfigurasi batas percobaan masuk gagal
LOGIN_WINDOW_MINUTES Server 15 Referensi konfigurasi jendela waktu rate limit (menit)
REPOSITORY_RETENTION_DAYS Maintenance 30 Lama retensi karya soft-deleted sebelum dihapus permanen oleh repositories-purge.ts
SDR_RELEASE Server CD <40-char git SHA> Tag image Docker yang dikelola otomatis oleh scripts/deploy-server.sh
NODE_ENV Runtime production Mode runtime Node.js / Next.js

5. Operasional Database, Penyimpanan Media, & Cron Pemeliharaan

Section titled “5. Operasional Database, Penyimpanan Media, & Cron Pemeliharaan”

5.1 Migrasi dan Inisialisasi Awal di Server

Section titled “5.1 Migrasi dan Inisialisasi Awal di Server”

Saat inisialisasi pertama atau pemulihan server baru di /opt/soedirman-digital-repository:

Terminal window
# 1. Terapkan seluruh migrasi SQL produksi (jangan gunakan migrate dev)
docker compose -p soedirman-digital-repository exec -T app ./node_modules/.bin/prisma migrate deploy
# 2. Jalankan seed kategori dasar & Super Admin awal (memakai variabel .env server)
docker compose -p soedirman-digital-repository exec -T app ./node_modules/.bin/tsx prisma/seed.ts

Jika perlu membuat atau memperbarui akun SUPER_ADMIN secara terpisah di luar seed.ts, jalankan:

Terminal window
docker compose -p soedirman-digital-repository exec -T app ./node_modules/.bin/tsx scripts/create-admin.ts

5.2 Penyimpanan Media (S3/MinIO vs Fallback Lokal)

Section titled “5.2 Penyimpanan Media (S3/MinIO vs Fallback Lokal)”
  • Mode Object Storage S3/R2/MinIO: Pastikan bucket memiliki kebijakan baca publik (s3:GetObject) untuk prefix gambar dan CORS mengizinkan GET/HEAD dari https://repo.p3mdi.id.
  • Mode Fallback Disk Lokal (public/uploads/): Jika S3 tidak dikonfigurasi atau tidak dapat dijangkau, lib/storage/s3-adapter.ts menyimpan berkas ke public/uploads/repositories/.... Pada lingkungan Docker Compose tanpa layanan S3 eksternal, pastikan direktori /app/public/uploads di-mount sebagai volume persisten agar gambar unggahan tidak hilang saat kontainer diganti.

Jadwalkan eksekusi berkala pada host VPS agar media yatim dan repositori terhapus tidak menumpuk:

# Bersihkan media yatim (> 24 jam) & rate-limit kedaluwarsa setiap hari pukul 02:00 WIB
0 2 * * * docker compose -p soedirman-digital-repository -f /opt/soedirman-digital-repository/compose.yaml exec -T app ./node_modules/.bin/tsx scripts/media-cleanup.ts --apply >> /var/log/sdr-media-cleanup.log 2>&1
# Hapus permanen repositori soft-delete melewati REPOSITORY_RETENTION_DAYS setiap Minggu pukul 03:00 WIB
0 3 * * 0 docker compose -p soedirman-digital-repository -f /opt/soedirman-digital-repository/compose.yaml exec -T app ./node_modules/.bin/tsx scripts/repositories-purge.ts --apply >> /var/log/sdr-repo-purge.log 2>&1

(Untuk simulasi aman sebelum eksekusi, jalankan skrip yang sama tanpa flag --apply.)


6. Pemantauan Kesehatan, Backup, dan Prosedur Rollback

Section titled “6. Pemantauan Kesehatan, Backup, dan Prosedur Rollback”
  • Periksa status aplikasi dan koneksi PostgreSQL secara langsung:
    Terminal window
    curl -fsS https://repo.p3mdi.id/api/health
  • Output sehat mengembalikan HTTP 200 dengan body JSON { "status": "ok", "timestamp": "..." }. Jika database terputus, endpoint mengembalikan HTTP 503.

Setiap kali deploy berjalan, scripts/deploy-server.sh otomatis membuat dump database ke /var/lib/sdr-cd/deployments/<timestamp>-<sha>/database.dump. Untuk backup atau pemulihan manual:

Terminal window
# Backup manual terkompresi
docker compose -p soedirman-digital-repository -f /opt/soedirman-digital-repository/compose.yaml \
exec -T db pg_dump -U sdr -d sdr -Fc > /var/backups/sdr_$(date +%Y%m%d).dump
# Pemulihan database dari dump
cat /var/lib/sdr-cd/deployments/<timestamp>-<sha>/database.dump | \
docker compose -p soedirman-digital-repository -f /opt/soedirman-digital-repository/compose.yaml \
exec -T db pg_restore -U sdr -d sdr --clean --if-exists
  1. Rollback Otomatis saat Deploy Gagal: Jika migrasi, update .env, startup kontainer, atau verifikasi /api/health gagal, blok trap rollback ERR di scripts/deploy-server.sh otomatis memulihkan $backup/env.bak (yang masih menunjuk ke SDR_RELEASE sebelumnya) dan menjalankan kembali kontainer app. (Skrip tidak me-restore database secara otomatis demi keamanan data; gunakan $backup/database.dump bila skema perlu dikembalikan.)
  2. Rollback Manual Pasca-Rilis:
    • Salin nilai SDR_RELEASE dari $backup/env.bak (atau jalankan deploy ulang commit master stabil sebelumnya lewat workflow_dispatch), atau jalankan kembali image soedirman-digital-repository:last-good.
    • Jika rilis baru telah menjalankan migrasi SQL yang tidak kompatibel mundur, pulihkan database.dump terlebih dahulu sebelum menyalakan kontainer versi sebelumnya.