Konfigurasi, Menjalankan Lokal, dan Deployment

Halaman ini merangkum tiga hal yang dibutuhkan untuk menjalankan repository: variabel environment, perintah npm, dan dua jalur deploy yang tersedia. Isi berkas data yang disajikan server dibahas di Model Data quran.json dan juz.json, sedangkan proses pengambilan datanya dibahas di Crawler: Pipeline Pengambilan Data.

Peta konfigurasi ke target deploy

config.js adalah satu-satunya modul yang memuat .env dengan path: '.env' eksplisit, lalu mengekspor tiga nilai ke pemakainya. Server tidak memakai config.js; api/server.js memanggil dotenv sendiri. Satu-satunya pemakai config.js adalah crawler/script.js. config.js:1-11¹ crawler/script.js:5² api/server.js:2³

graph TD
  env[".env"] --> cfg["config.js"]
  env --> srv["api/server.js"]
  cfg --> crawl["crawler/script.js"]
  cfg --> mongo["MONGODB_URI tidak dipakai"]
  crawl --> qjson["data/quran.json"]
  qjson --> srv
  srv --> vjson["vercel.json @vercel/node"]
  srv --> appjson["app.json heroku-18"]
  vjson --> gha["vercel_production.yml"]
  appjson --> docker["dockerfile.build"]
  gha --> vtarget["Vercel production"]
  docker --> htarget["Heroku dyno"]
  style env fill:#f59e0b,color:#000
  style cfg fill:#f59e0b,color:#000
  style vjson fill:#f59e0b,color:#000
  style appjson fill:#f59e0b,color:#000
  style gha fill:#f59e0b,color:#000
  style docker fill:#f59e0b,color:#000
  style crawl fill:#8b5cf6,color:#fff
  style qjson fill:#336791,color:#fff
  style mongo fill:#dc2626,color:#fff
  style srv fill:#2d7d46,color:#fff
  style vtarget fill:#2d7d46,color:#fff
  style htarget fill:#2d7d46,color:#fff
%% fig: Sumber konfigurasi menuju target deploy
%% desc: Variabel .env masuk ke config.js dan api/server.js, crawler menghasilkan data/quran.json, lalu api/server.js dikemas oleh vercel.json atau app.json menuju masing-masing target deploy.

Variabel environment

config.js mendestrukturisasi tiga nama dari process.env dan mengekspornya kembali dengan nama yang sama. .env.example mendeklarasikan dua nama yang berbeda dari yang dibaca config.js. config.js:3-11⁴ .env.example:1-3⁵

⚠️ Awalan SOURCE_SOURCE_ di .env.example tidak cocok dengan SOURCE_API_BASEURL dan SOURCE_API_BASEURL_2 yang dibaca config.js. Menyalin berkas contoh apa adanya menghasilkan undefined pada URL crawler. .env.example:1-3⁵ config.js:4-6⁹

Komponen .env sendiri tidak masuk ke commit; .gitignore memuat .env bersama node_modules, quran-tafsir.json, dan .vercel. .gitignore:1-4

Perintah npm

package.json menetapkan api/server.js sebagai main dan menyediakan empat skrip. package.json:4¹⁰ package.json:9-14¹¹

dotenv ada di dependencies, sehingga npm install sudah cukup untuk npm start di lingkungan baru. nodemon dan isomorphic-fetch berada di devDependencies, jadi npm run dev dan npm run crawl membutuhkan dependensi development. package.json:15-24¹²

api/server.js menentukan port dari process.env.PORT dengan nilai cadangan 3000, lalu mencatat 'Server running at port:' saat listen berhasil. api/server.js:8⁸ api/server.js:16-18¹³

⚠️ npm run crawl menulis ulang data/quran.json secara penuh lewat writeFile('./data/quran.json', ...) setelah mengulang surah 1 sampai 114. Perintah ini juga membaca ../data/quran-tafsir.json yang di-ignore oleh .gitignore, sehingga hasil clone bersih tidak bisa menjalankannya sebelum berkas itu disediakan sendiri. crawler/script.js:203¹⁴ crawler/script.js:10¹⁵ .gitignore:2-2

Deploy ke Vercel

vercel.json memakai @vercel/node untuk api/server.js dan mengarahkan seluruh path /.* ke berkas itu, sehingga tidak ada static build terpisah. vercel.json:1-11¹⁶

.vercelignore mengeluarkan screenshots dan crawler dari unggahan, jadi kode crawler tidak ikut ke deploy. .vercelignore:1-2

Workflow Vercel Production Deployment berjalan pada push ke branch main dan menjalankan lima langkah berurutan. .github/workflows/vercel_production.yml:1-27¹⁷

graph LR
  trig["push ke main"] --> co["actions/checkout@v2"]
  co --> inst["npm install --global vercel@latest"]
  inst --> pull["vercel pull --environment=production"]
  pull --> build["vercel build --prod"]
  build --> dep["vercel deploy --prebuilt --prod"]
  dep --> live["Vercel production"]
  style trig fill:#f59e0b,color:#000
  style co fill:#f59e0b,color:#000
  style inst fill:#f59e0b,color:#000
  style pull fill:#8b5cf6,color:#fff
  style build fill:#8b5cf6,color:#fff
  style dep fill:#2d7d46,color:#fff
  style live fill:#2d7d46,color:#fff
%% fig: Urutan langkah deploy Vercel di GitHub Actions
%% desc: Push ke main memicu checkout, pemasangan Vercel CLI, penarikan environment, build artefak, lalu deploy prebuilt ke production.

⚠️ Di blok env workflow, VERCEL_ORG_ID diisi dari secrets.VERCEL_TEAM_ID, bukan dari secret organisasi tersendiri. Nilai VERCEL_TEAM_ID dan VERCEL_ORG_ID jadi selalu sama, sehingga vercel pull mengandalkan VERCEL_PROJECT_ID untuk membedakan proyek. .github/workflows/vercel_production.yml:2-5¹⁸

Menurut README, deploy inilah yang melayani alamat https://api.quran.gading.dev, dan README menyarankan deploy mandiri karena alamat tersebut dibatasi rate limiter. README.md:5-11¹⁹

Deploy ke Heroku

app.json mendefinisikan nama aplikasi, stack heroku-18, dan satu buildpack heroku/nodejs. Tidak ada skrip start khusus di berkas ini; Heroku memakai skrip start dari package.json. app.json:2-12²⁰ package.json:11²¹

dockerfile.build adalah image untuk tahap build, bukan runtime: basisnya heroku/heroku:18 dan isinya hanya RUN npm install, tanpa CMD atau EXPOSE. dockerfile.build:1-2²²

Perbandingan jalur deploy