Add comprehensive documentation for CI/CD pipeline, NATS, security practices, Tailscale networking, and troubleshooting guide

- Created CI/CD pipeline documentation detailing workflows, triggers, and actions for `asepharyana-hub`. - Added NATS + JetStream guide covering architecture, configuration, CLI tools, and event topics. - Introduced a security guide outlining best practices for secrets management, TLS, container security, and access control. - Documented Tailscale networking setup and troubleshooting for connectivity between VPS and bare-metal nodes. - Compiled a troubleshooting guide addressing common issues across deployment, Dapr, NATS, Traefik, Tailscale, Docker, database, and submodules.
2026-07-22 16:35:38 +07:00
parent 5025d103e9
commit df71487563
9 changed files with 2060 additions and 1 deletions
@@ -0,0 +1,206 @@
+# Development Guide
+
+Panduan setup lingkungan development lokal untuk kontributor `asepharyana-hub`.
+
+## Prasyarat
+
+| Tool | Versi Minimal | Catatan |
+|------|---------------|---------|
+| Git | 2.40+ | Submodule support |
+| Docker | 24+ | Dengan Docker Compose v2 plugin |
+| Rust | 1.85+ | Hanya untuk `apps/scraper` |
+| Bun | 1.x | Root tooling (Biome) |
+| Dapr CLI | 1.14+ | Opsional, untuk development dengan Dapr |
+
+## Setup Awal
+
+```bash
+# 1. Clone repo
+git clone https://github.com/asepharyana/asepharyana-hub.git
+cd asepharyana-hub
+
+# 2. Init submodules
+make init-submodules
+
+# 3. Setup environment
+cp .env.example .env
+# Edit .env sesuai kebutuhan lokal
+
+# 4. Install root dependencies
+bun install
+```
+
+## Menjalankan Infrastruktur Lokal
+
+Beberapa service membutuhkan Redis. Jalankan dengan:
+
+```bash
+make dev
+# atau equivalen:
+docker compose -f infra/compose/shared.yml up -d
+```
+
+Ini akan menjalankan Redis Alpine di `localhost:6379`.
+
+### (Opsional) NATS Lokal
+
+Jika service membutuhkan pub/sub:
+
+```bash
+docker compose -f infra/compose/nats.yml up -d
+# NATS client: localhost:4222
+# NATS monitor: localhost:8222
+```
+
+### (Opsional) Dapr Placement Lokal
+
+Jika service membutuhkan sidecar Dapr:
+
+```bash
+docker compose -f infra/compose/dapr.yml up -d
+# Dapr placement: localhost:50005
+```
+
+## Menjalankan Service Lokal
+
+### Scraper API (Rust)
+
+```bash
+# Pastikan Redis sudah running (make dev)
+cd apps/scraper
+
+# Cargo run
+cargo run
+
+# Dengan Dapr sidecar (jika placement running)
+dapr run \
+  --app-id scraper-api \
+  --app-port 4091 \
+  --dapr-http-port 3500 \
+  --resources-path ../../infra/dapr/components \
+  -- cargo run
+```
+
+### Dengan Docker Compose (Full Stack)
+
+Untuk menjalankan semua service sekaligus:
+
+```bash
+docker compose \
+  -f infra/compose/shared.yml \
+  -f infra/compose/nats.yml \
+  -f infra/compose/dapr.yml \
+  -f infra/compose/scraper.yml \
+  --env-file .env \
+  up -d
+```
+
+Untuk service baru, tambahkan compose file-nya ke daftar.
+
+## Update Submodules
+
+### Pull latest dari semua submodule
+
+```bash
+make update-submodules
+# atau:
+git submodule update --remote --merge --recursive
+```
+
+### Check status submodule
+
+```bash
+make status
+# atau:
+git submodule status
+```
+
+### Sync .env ke submodule
+
+```bash
+bash scripts/2updateenv.sh
+# Copy .env root ke apps/*/
+```
+
+## Linting & Formatting
+
+Root repo menggunakan **Biome** untuk linting dan formatting:
+
+```bash
+bun run check    # Lint + format + write
+bun run ci       # CI mode (no write, exit code on issues)
+bun run lint     # Lint only
+bun run format   # Format only
+```
+
+## Build Docker Image Lokal
+
+```bash
+# Scraper API
+docker build -f infra/docker/scraper.Dockerfile -t scraper-api:local .
+
+# Service baru: tambahkan Dockerfile di infra/docker/
+```
+
+## Testing
+
+Saat ini belum ada test runner di root level. Masing-masing submodule mengelola testing sendiri:
+
+```bash
+# Scraper API (Rust)
+cd apps/scraper && cargo test
+```
+
+## Validasi YAML
+
+Sebelum commit perubahan infra, validasi semua file YAML:
+
+```bash
+python -c "
+import pathlib, yaml
+for p in pathlib.Path('infra').rglob('*.yml'):
+    with open(p) as f: yaml.safe_load(f)
+    print(f'OK {p}')
+for p in pathlib.Path('infra').rglob('*.yaml'):
+    with open(p) as f: yaml.safe_load(f)
+    print(f'OK {p}')
+"
+
+for f in infra/compose/*.yml; do
+  docker compose -f "$f" config >/dev/null && echo "OK $f"
+done
+```
+
+## Git Workflow
+
+### Commit Convention
+
+```
+<type>(<scope>): <description>
+```
+
+Type: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`, `perf`, `style`
+Scope: `scraper`, `infra`, `ci`, `dapr`, `nats`, `docs`, `deps`, `scripts`, `root`
+
+Contoh:
+```
+feat(scraper): add image cache endpoint
+fix(infra): correct Traefik rate-limit config
+chore(deps): bump biome to 2.5.0
+```
+
+### Branch Strategy
+
+- `main` — production branch, push triggers CI/CD
+- Fitur baru: branch dari `main`, PR ke `main`
+- Submodule development: dilakukan di repo masing-masing, hub hanya update pointer
+
+## Deployment ke VPS
+
+Push ke `main` otomatis trigger CI/CD. Untuk trigger manual:
+
+```bash
+gh workflow run deploy-docker.yml
+```
+
+Lihat `docs/DEPLOYMENT.md` untuk detail.