Memulai Cepat

Hydro dapat dicoba lewat dua jalur: satu perintah docker compose up --build yang menyalakan seluruh stack di dalam container, atau mode development dua terminal dengan database di container sementara Django dan Next.js berjalan langsung di mesin pengembang. Keduanya memakai akun demo yang sama. Panduan ini hanya membahas langkah menyalakan dan memeriksa aplikasi; bentuk sistemnya dijelaskan di Arsitektur Sistem.

Mencoba dengan satu perintah

Jalur tercepat hanya membutuhkan Docker. Perintah docker compose up --build membangun image web dari deploy/web.Dockerfile dan image api dari direktori backend/, lalu menyalakan db README.md:13-23 compose.yaml:4-14. Berkas compose.yaml sendiri menyatakan tujuannya untuk mencoba aplikasi di komputer sendiri, sedangkan produksi memakai compose.prod.yaml compose.yaml:1-2.

graph TD
  A["docker compose up --build"] --> B["db: postgres:18.1"]
  B -->|"pg_isready -U hydro -d hydro"| C["api: manage.py migrate --noinput"]
  C --> D["api: manage.py isi_demo"]
  D --> E["api: gunicorn config.wsgi 0.0.0.0:8000"]
  E --> F["web: nginx 127.0.0.1:8080"]
  F --> G["http://localhost:8080"]
  style A fill:#f59e0b,color:#000
  style B fill:#336791,color:#fff
  style E fill:#2d7d46,color:#fff
  style G fill:#8b5cf6,color:#fff
%% fig: Urutan boot satu perintah compose
%% desc: Compose menyalakan db lebih dulu, menjalankan migrate dan isi_demo di api, lalu menyajikan frontend statis lewat nginx di port 8080.

Fig. 1: Urutan boot satu perintah composeCompose menyalakan db lebih dulu, menjalankan migrate dan isi_demo di api, lalu menyajikan frontend statis lewat nginx di port 8080.

Urutan boot diatur oleh depends_on. Layanan api menunggu db berstatus sehat, dan web menunggu api sehat compose.yaml:4-14. Kesehatan db diuji dengan pg_isready -U hydro -d hydro pada interval: 3s dengan retries: 20 compose.yaml:43-46. Container api menjalankan tiga perintah berurutan dalam satu sh -c: migrate --noinput, lalu isi_demo, lalu exec gunicorn config.wsgi --bind 0.0.0.0:8000 --workers 2 compose.yaml:25-28.

Layanan web hanya berisi Nginx dan berkas statis. Konfigurasi deploy/nginx.lokal.conf meneruskan prefiks /api/ ke http://api:8000 dan menyajikan sisanya lewat try_files, tanpa HTTPS deploy/nginx.lokal.conf:10-17.

Layanan	Sumber	Port	Peran saat boot
`web`	`build` dari `deploy/web.Dockerfile`	`127.0.0.1:8080:8080`	Nginx statis, proxy `/api/`
`api`	`build: ./backend`	internal `8000`	`migrate`, `isi_demo`, `gunicorn`
`db`	`postgres:18.1`	internal `5432`	Menyimpan `pgdata`, healthcheck `pg_isready`

Buka http://localhost:8080 setelah semua layanan sehat README.md:13-23. Hentikan dengan docker compose down README.md:23.

⚠️ Mode ini memakai password contoh dan tanpa HTTPS, jadi jangan dipakai untuk produksi. Menambahkan opsi -v pada docker compose down menghapus volume pgdata dan media sekaligus, termasuk seluruh data yang sudah dicatat README.md:23.

Mode development dua terminal

Jalur ini memberi reload otomatis saat kode diubah dan membutuhkan Docker, Python 3.13+, serta Node.js 26 README.md:27. Langkah lengkapnya berurutan dari penyalaan database sampai npm run dev README.md:25-43.

Terminal pertama hanya menyalakan database lewat compose.dev.yaml. Berkas itu mendefinisikan satu layanan db berbasis postgres:18.1, memetakan 127.0.0.1:5433:5432, dan memakai volume pgdata_dev compose.dev.yaml:1-12. Port 5433 itu cocok dengan nilai bawaan POSTGRES_PORT pada konfigurasi database Django backend/config/settings.py:83-84.

Seluruh perintah backend dijalankan lewat backend/manage.py. Skrip itu menyetel DJANGO_SETTINGS_MODULE=config.settings lalu meneruskan argumen ke execute_from_command_line backend/manage.py:6-10.

Ekspor DJANGO_DEBUG=1 sebelum migrate dan runserver. Tanpa variabel itu DEBUG bernilai salah, dan Django mewajibkan DJANGO_SECRET_KEY terisi backend/config/settings.py:15-23. Perintah isi_demo juga menolak berjalan saat DEBUG mati dengan CommandError("isi_demo hanya untuk development.") backend/akun/management/commands/isi_demo.py:19-21.

Terminal kedua berpindah ke frontend, menjalankan npm install, lalu npm run dev README.md:25-43. next dev menyajikan halaman di port 3000 README.md:45-47 dan menulis ulang prefiks /api/ ke API_DEV yang bawaannya http://127.0.0.1:8000 frontend/next.config.ts:5 frontend/next.config.ts:30-35. Rewrite itu hanya aktif saat development; build produksi memakai output: "export" sehingga yang dihasilkan hanya berkas statis frontend/next.config.ts:18-25.

graph TD
  T1["Terminal 1: compose.dev.yaml up -d --wait"] --> T2["db di 127.0.0.1:5433"]
  T2 --> T3["manage.py migrate"]
  T3 --> T4["manage.py isi_demo"]
  T4 --> T5["manage.py runserver :8000"]
  T6["Terminal 2: npm run dev"] --> T7["next dev :3000"]
  T7 -->|"rewrite /api/:path*"| T5
  style T1 fill:#f59e0b,color:#000
  style T2 fill:#336791,color:#fff
  style T5 fill:#2d7d46,color:#fff
  style T7 fill:#8b5cf6,color:#fff
%% fig: Dua terminal pada mode development
%% desc: Terminal pertama menyiapkan database, migrasi, dan data demo; terminal kedua menjalankan next dev yang meneruskan /api/ ke runserver Django.

Fig. 2: Dua terminal pada mode developmentTerminal pertama menyiapkan database, migrasi, dan data demo; terminal kedua menjalankan next dev yang meneruskan /api/ ke runserver Django.

Langkah	Perintah	Keterangan
Nyalakan database	`docker compose -p hydro-dev -f compose.dev.yaml up -d --wait`	Hanya layanan `db`
Pasang dependensi	`.venv/Scripts/pip install -r requirements-dev.txt`	Linux/macOS: `.venv/bin/pip`
Nyalakan debug	`export DJANGO_DEBUG=1`	PowerShell: `$env:DJANGO_DEBUG=1`
Siapkan skema	`python manage.py migrate`	Memakai `POSTGRES_PORT` `5433`
Isi data demo	`python manage.py isi_demo`	Ditolak kalau `DEBUG` mati
Jalankan API	`python manage.py runserver`	Port `8000`
Jalankan frontend	`npm run dev`	Port `3000`

Akun demo

isi_demo membuat tiga akun dengan password hydro-demo-123 bila belum ada: pemilik, admin, dan gudang backend/akun/management/commands/isi_demo.py:22-30. Setelah selesai perintah itu mencetak Data contoh siap. Password: hydro-demo-123 backend/akun/management/commands/isi_demo.py:69.

Username	Peran (`peran_id`)	Izin	2FA
`pemilik`	`pemilik`	Seluruh `SEMUA_IZIN`	Wajib
`admin`	`admin_penjualan`	`lihat_produk`, `kelola_transaksi`	Tidak wajib
`gudang`	`staf_gudang`	`lihat_produk`, `kelola_stok`	Tidak wajib

Pemetaan izin per peran diambil langsung dari IZIN_PERAN backend/inti/izin.py:31-35. Properti wajib_2fa bernilai benar hanya untuk peran PEMILIK, dan belum_aktifkan_2fa menjadi benar selama pengguna itu belum punya authenticator TOTP backend/akun/models.py:36-42. Selama kondisi itu bertahan, request ditolak dengan Wajib2FA yang memakai kode wajib_2fa dan pesan Aktifkan 2FA terlebih dahulu untuk melanjutkan. backend/inti/izin.py:38-40. Karena itu, login sebagai pemilik langsung berhenti di layar aktivasi 2FA; langkah aktivasi dan pemulihannya ada di Autentikasi, 2FA, dan Izin Peran.

Pemeriksaan mutu

Pemeriksaan dijalankan dari dua direktori: backend untuk Python dan frontend untuk TypeScript README.md:49-60.

Direktori	Perintah	Yang diperiksa
`backend`	`ruff check . && ruff format --check .`	Lint dan format
`backend`	`mypy .`	Tipe statis Python
`backend`	`pytest --create-db`	Test Django
`frontend`	`npm run typecheck`	`tsc --noEmit`
`frontend`	`npm run build`	Build Next.js

pytest.ini menyetel DJANGO_SETTINGS_MODULE = config.settings dan addopts = -q --reuse-db, sehingga database test dipakai ulang antarjalankan; opsi --create-db di dokumentasi memaksa pembuatan ulang skema test backend/pytest.ini:1-4.

Setelah endpoint berubah, perbarui tipe TypeScript agar kedua aplikasi tetap selaras: manage.py spectacular --file schema.yaml --fail-on-warn di backend, lalu npm run tipe-api di frontend README.md:62-67. Skrip tipe-api menjalankan openapi-typescript ../backend/schema.yaml -o src/lib/api-types.ts, dan typecheck menjalankan tsc --noEmit frontend/package.json:5-11.

Urutan job yang sama juga dijalankan di pipeline otomatis; rinciannya ada di Pengujian dan Pipeline CI. Untuk menguji image hasil build seperti produksi di komputer lokal, gabungkan compose.prod.yaml dengan compose.local.yaml memakai --env-file .env.local README.md:112-118, dan ikuti langkahnya di Deploy, Backup, dan Operasi VPS.