Local Development

Panduan menjalankan backend ATE di mesin lokal untuk keperluan pengembangan.

Prasyarat

Komponen	Versi / catatan
Node.js	14.x (sesuai engines di package.json). Disarankan memakai nvm agar bisa berpindah versi.
PostgreSQL	Database utama (dialect postgres).
Sequelize CLI	Untuk migrasi (npx sequelize-cli).
Elasticsearch	Opsional untuk fitur reporting/log (ES_ENABLE=true). Bisa dimatikan saat dev.
Akses layanan eksternal	Zimbra, ZoneMTA, Zoho, Xendit, Linode S3 — kebanyakan memerlukan kredensial. Untuk dev, gunakan kredensial sandbox/staging.

Node.js 14 sudah EOL

Node 14 tidak lagi mendapat security update. Untuk dev baru, pertimbangkan menjalankan via Docker dengan image Node 14, atau ikuti Roadmap Migrasi untuk upgrade ke Node LTS.

Langkah menjalankan

# 1. Install dependency
npm install

# 2. Siapkan environment
cp .env.example .env
# lalu isi nilai-nilai env (lihat halaman Konfigurasi Environment)

# 3. Jalankan migrasi database
npx sequelize-cli db:migrate

# (opsional) jalankan seeder
npx sequelize-cli db:seed:all

# 4. Jalankan server (mode dev dengan nodemon)
npm run dev
# atau
npm run start:local

Server akan listen di PORT (default 5000). Dokumentasi Swagger tersedia di http://localhost:5000/api-docs.

ENV vs NODE_ENV

Konfigurasi database memakai variabel ENV (bukan NODE_ENV). Lihat config/config.js → helpers/config.helper.js:

• Jika ENV !== "production" → koneksi pakai DB_USERNAME, DB_PASSWORD, DB_DATABASE, DB_HOST, DB_PORT, DB_DIALECT.
• Jika ENV === "production" → koneksi pakai DATABASE_URL dengan SSL.

Catatan: default DB_PORT di helper adalah 3306 (port MySQL) — untuk PostgreSQL biasanya 5432, jadi selalu set DB_PORT secara eksplisit.

Skrip npm penting

Skrip	Fungsi
npm start	Jalankan production (node server.js)
npm run dev / start:local / start:dev	Jalankan dengan nodemon (auto-reload)
npm test	Jalankan unit test (Jest)
npm run test:e2e	Jalankan e2e test
npm run cron:*	Menjalankan job/cron tertentu (lihat Background Jobs)

Menjalankan cron / job secara manual

Job asinkron dijalankan sebagai proses terpisah lewat job-runner.js:

# Pola umum
node job-runner <path-skrip-di-folder-cron> [argumen]

# Contoh
node job-runner job-reset-quota-mail
node job-runner invoices/recurring-invoice/job-recurring-invoice

Daftar lengkap skrip cron ada di Background Jobs & Cron.

Menjalankan situs dokumentasi ini

Dokumentasi ini adalah subproject VitePress terpisah di folder docs/ (butuh Node 18+, terpisah dari runtime app Node 14):

cd docs
npm install
npm run docs:dev      # mode pengembangan (live preview)
npm run docs:build    # build static site ke .vitepress/dist
npm run docs:preview  # preview hasil build

Struktur kode yang perlu dipahami lebih dulu

Urutan eksplorasi yang disarankan untuk engineer baru:

1. app.js & server.js — entry point & middleware.
2. routes/index.js — peta endpoint utama.
3. models/ & models/index.js — skema data (Basis Data).
4. controllers/ (satu fitur, mis. controllers/biliings/checkoutServicePackages/) — pola controller+service.
5. helpers/ — wrapper integrasi (Referensi Integrasi).
6. cron/ + job-runner.js — pekerjaan asinkron.