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 |
1. Topologi & Lingkungan Produksi P3MDI
Section titled “1. Topologi & Lingkungan Produksi P3MDI”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 olehproxy.tske/s/[alias]) - Direktori Aplikasi Live di Server:
/opt/soedirman-digital-repository(compose.yamldan.env) - Direktori State CD & Rilis:
/var/lib/sdr-cd(repository.git,releases/,deployments/,deployed-commit) - Skrip Deploy Server:
/usr/local/sbin/sdr-deploy(disinkronkan dariscripts/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"]
2. Konfigurasi Docker Image (Dockerfile)
Section titled “2. Konfigurasi Docker Image (Dockerfile)”Image produksi dibangun menggunakan Dockerfile di root repositori:
- Base Image:
node:24-bookworm-slimdengan paket sistemca-certificatesdanopenssl, berjalan di bawah user non-rootnode. - Argumen Build:
ARG NEXT_PUBLIC_SITE_URL=https://repo.p3mdi.iddisematkan ke environment build agar URL kanonik, sitemap, dan metadata Open Graph mengarah ke domain produksi. - Tahap Build:
npm ci --no-audit --no-fund(denganDATABASE_URLdummy saat tahap build)npx prisma generate./node_modules/.bin/next build
- Runtime Container:
NODE_ENV=production, mengekspos port3000, 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)”- Validasi sintaks skrip CD:
bash -n scripts/deploy-server.sh. - Instalasi bersih:
npm ci --no-audit --no-fund. - Generasi & validasi Prisma:
npm run db:generate && npm run db:validate. - Pemeriksaan tipe ketat:
npm run typecheck. - Linter (advisory):
npm run lint(continue-on-error: true). - Audit dependensi produksi:
npm audit --omit=dev --audit-level=high. - Pemindaian kebocoran rahasia pada riwayat Git: container
ghcr.io/gitleaks/gitleaks:v8.24.2(git --redact --log-opts=HEAD .). - 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_SHAmasih merupakanHEADterbaru darirefs/heads/masterlewat GitHub API (gh api). - Membuka koneksi SSH terotentikasi ke
root@$DEPLOY_HOSTmenggunakanDEPLOY_SSH_KEYdanDEPLOY_KNOWN_HOSTS(denganStrictHostKeyChecking=yes), mengirimkan${{ github.token }}secara aman melaluistdin(tidak pernah ditulis permanen ke disk atau argumen CLI), serta mengeksekusi perintahdeploy <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”- Mengunci eksekusi dengan
flock -w 900pada/var/lock/sdr-deploy.lock. - Memvalidasi argumen tepat berupa
deploy <40-hex SHA>dan ketersediaan/opt/soedirman-digital-repository/.envsertacompose.yaml. - Mengambil pembaruan bare mirror
/var/lib/sdr-cd/repository.gitmemakai header otorisasi token sementara daristdin, lalu memastikan SHA target cocok denganrefs/remotes/origin/master. - Memastikan sisa ruang disk pada
/opt/soedirman-digital-repositoryminimal2 GiB. - Mengekstrak arsip commit ke
/var/lib/sdr-cd/releases/<sha>dan membangun imagesoedirman-digital-repository:<sha>. - Membuat direktori backup
/var/lib/sdr-cd/deployments/<timestamp>-<sha>: menyalin.env(chmod 600), menandai image kontainer aktif sebelumnya sebagaisoedirman-digital-repository:last-good, dan membuat dump database PostgreSQL terkompresi (pg_dump -U sdr -d sdr -Fc > database.dump). - Menjalankan migrasi database:
SDR_RELEASE=<sha> compose run --rm --no-deps -T app ./node_modules/.bin/prisma migrate deploy. - Memperbarui nilai
SDR_RELEASE=<sha>di.envsecara atomik (mempertahankan hak akses0600) menggunakan Pythontempfile+os.replace. - Menjalankan ulang layanan
app:compose up -d --no-deps --wait --wait-timeout 120 app. - Memverifikasi health check internal (
http://127.0.0.1:3000/api/health) serta endpoint HTTPS publik ($site_url/api/healthdan$site_url/repositories). - Memperbarui skrip
/usr/local/sbin/sdr-deploy, mencatat SHA dideployed-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:
# 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.tsJika perlu membuat atau memperbarui akun SUPER_ADMIN secara terpisah di luar seed.ts, jalankan:
docker compose -p soedirman-digital-repository exec -T app ./node_modules/.bin/tsx scripts/create-admin.ts5.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 mengizinkanGET/HEADdarihttps://repo.p3mdi.id. - Mode Fallback Disk Lokal (
public/uploads/): Jika S3 tidak dikonfigurasi atau tidak dapat dijangkau,lib/storage/s3-adapter.tsmenyimpan berkas kepublic/uploads/repositories/.... Pada lingkungan Docker Compose tanpa layanan S3 eksternal, pastikan direktori/app/public/uploadsdi-mount sebagai volume persisten agar gambar unggahan tidak hilang saat kontainer diganti.
5.3 Penjadwalan Tugas Pemeliharaan (Cron)
Section titled “5.3 Penjadwalan Tugas Pemeliharaan (Cron)”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 WIB0 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 WIB0 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”6.1 Pemantauan Kesehatan (/api/health)
Section titled “6.1 Pemantauan Kesehatan (/api/health)”- Periksa status aplikasi dan koneksi PostgreSQL secara langsung:
Terminal window curl -fsS https://repo.p3mdi.id/api/health - Output sehat mengembalikan HTTP
200dengan body JSON{ "status": "ok", "timestamp": "..." }. Jika database terputus, endpoint mengembalikan HTTP503.
6.2 Backup & Restore Database Manual
Section titled “6.2 Backup & Restore Database Manual”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:
# Backup manual terkompresidocker 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 dumpcat /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-exists6.3 Prosedur Rollback
Section titled “6.3 Prosedur Rollback”- Rollback Otomatis saat Deploy Gagal: Jika migrasi, update
.env, startup kontainer, atau verifikasi/api/healthgagal, bloktrap rollback ERRdiscripts/deploy-server.shotomatis memulihkan$backup/env.bak(yang masih menunjuk keSDR_RELEASEsebelumnya) dan menjalankan kembali kontainerapp. (Skrip tidak me-restore database secara otomatis demi keamanan data; gunakan$backup/database.dumpbila skema perlu dikembalikan.) - Rollback Manual Pasca-Rilis:
- Salin nilai
SDR_RELEASEdari$backup/env.bak(atau jalankan deploy ulang commitmasterstabil sebelumnya lewatworkflow_dispatch), atau jalankan kembali imagesoedirman-digital-repository:last-good. - Jika rilis baru telah menjalankan migrasi SQL yang tidak kompatibel mundur, pulihkan
database.dumpterlebih dahulu sebelum menyalakan kontainer versi sebelumnya.
- Salin nilai