diff --git a/server-connection/context-index.md b/server-connection/context-index.md new file mode 100644 index 0000000..fb20459 --- /dev/null +++ b/server-connection/context-index.md @@ -0,0 +1,91 @@ +# Context Index (AI Entry Point) — server-connection + +> **Versi Dokumen:** 1.0.0 +> **Terakhir Diperbarui:** 2026-06-25 +> **Status:** Aktif +> **Pemilik:** Tim IT GIS Portal + +--- + +## Tujuan + +Dokumen ini merupakan **titik masuk utama (Single Entry Point)** bagi seluruh AI Agent dan Developer untuk workspace **server-connection**. + +Setiap AI **WAJIB** membaca dokumen ini terlebih dahulu sebelum melakukan analisis, implementasi, perubahan kode, refactoring, penghapusan, deployment, maupun pembuatan dokumentasi. + +--- + +## Filosofi + +- Dokumentasi adalah bagian dari source code. +- Repository merupakan sumber kebenaran utama (Single Source of Truth). +- AI tidak boleh mengandalkan riwayat percakapan. + +--- + +## Proyek dalam Workspace Ini + +| Proyek | URL | Status | Context Index | +|--------|-----|--------|---------------| +| **geonet-console** | https://console.gisportal.id | ✅ Production | [`geonet-console/context-index.md`](./geonet-console/context-index.md) | +| **databaselist** | https://databaselist.gisportal.id | ⚠️ Legacy (digantikan geonet-console) | — | + +> AI yang bekerja pada proyek spesifik **wajib membaca context-index proyek tersebut**, bukan file ini. + +--- + +## Infrastruktur Server + +| Role | IP | OS | SSH Command | +|------|----|----|-------------| +| Reverse Proxy | 10.100.1.24 | Linux (Debian) | `ssh -m hmac-sha1 root@10.100.1.24 -p 22` | +| Database (PostgreSQL + SQL Server) | 10.100.1.25 | Linux | `ssh -m hmac-sha1 root@10.100.1.25 -p 22` | +| Active Directory / LDAP | 10.100.1.40 | Windows Server | `ssh -m hmac-sha1 Administrator@10.100.1.40 -p 22` | +| NAS QNAP TS-932X | 10.100.1.10 | QTS | `ssh -i "$env:USERPROFILE\.ssh\id_ed25519" -o IdentitiesOnly=yes -m hmac-sha1 admin@10.100.1.10 -p 22` | +| Ollama AI (VM) | 10.100.1.26 | Ubuntu 22.04 | `ssh -i "$env:USERPROFILE\.ssh\id_rsa_geonet_laptop" -o IdentitiesOnly=yes -m hmac-sha1 root@10.100.1.26 -p 22` | +| Zabbix Monitor | 10.100.1.42 | Linux | `ssh -m hmac-sha1 root@10.100.1.42 -p 22` | + +> AI **wajib minta persetujuan user** sebelum menjalankan perintah SSH apapun. +> NAS QNAP & Ollama: wajib PowerShell (bukan CMD) agar `$env:USERPROFILE` terbaca. + +--- + +## Stack yang Berjalan di Reverse Proxy (10.100.1.24) + +| Stack | Path | Container | Port | +|-------|------|-----------|------| +| geonet-console | `/opt/stacks/geonet-console` | `geonet-console` | `8091` | +| my-portal (Next.js PWA) | `/opt/stacks/my-portal` | `my-portal` | `8092` | +| databaselist (legacy) | `/opt/stacks/databaselist` | `databaselist` | (legacy) | + +**Nginx configs:** `/etc/nginx/conf.d/production/` +**OSS proxy:** `/etc/nginx/conf.d/nas.conf` + +--- + +## Cara Transfer File ke Server (Windows → Linux) + +```powershell +# 1. Buat archive (tanpa vendor, .git) +tar -czf "$env:TEMP\project.tar.gz" ` + --exclude="vendor" --exclude=".git" --exclude="node_modules" ` + -C "D:\Project\app on git\server-connection\geonet-console" . + +# 2. Upload — WAJIB pakai Start-Process di PowerShell +Start-Process -FilePath "cmd.exe" -ArgumentList ` + '/c ssh -m hmac-sha1 root@10.100.1.24 -p 22 "cat > /tmp/project.tar.gz" < "%TEMP%\project.tar.gz"' ` + -Wait -NoNewWindow + +# 3. Extract di server +ssh -m hmac-sha1 root@10.100.1.24 -p 22 "tar -xzf /tmp/project.tar.gz -C /opt/stacks/geonet-console && rm /tmp/project.tar.gz" +``` + +> ⚠️ **JANGAN overwrite `.env`** saat deploy — `.env` server berisi credentials production. + +--- + +## Penutup + +Untuk detail implementasi setiap proyek, baca context-index masing-masing: + +- **geonet-console** → [`geonet-console/context-index.md`](./geonet-console/context-index.md) diff --git a/server-connection/geonet-console/context-index.md b/server-connection/geonet-console/context-index.md new file mode 100644 index 0000000..953121e --- /dev/null +++ b/server-connection/geonet-console/context-index.md @@ -0,0 +1,351 @@ +# Context Index (AI Entry Point) — geonet-console + +> **Versi Dokumen:** 1.0.0 +> **Terakhir Diperbarui:** 2026-06-25 +> **Status:** Aktif +> **Pemilik:** Tim IT GIS Portal + +--- + +## Tujuan + +Dokumen ini merupakan **titik masuk utama (Single Entry Point)** bagi seluruh AI Agent dan Developer untuk proyek **geonet-console**. + +Setiap AI **WAJIB** membaca dokumen ini terlebih dahulu sebelum melakukan analisis, implementasi, perubahan kode, refactoring, penghapusan, deployment, maupun pembuatan dokumentasi. + +Dokumen ini **bukan** tempat menyimpan seluruh informasi proyek, melainkan **peta navigasi** menuju seluruh dokumentasi yang tersedia. + +--- + +## Filosofi Proyek + +Proyek ini menerapkan prinsip **AI Native Development**. + +Artinya: + +- Dokumentasi adalah bagian dari source code. +- Setiap perubahan wajib terdokumentasi. +- Repository merupakan sumber kebenaran utama (Single Source of Truth). +- AI tidak boleh mengandalkan riwayat percakapan. +- Seluruh pengetahuan proyek harus tersimpan dalam repository. + +--- + +## Aturan Utama AI + +Sebelum melakukan pekerjaan apa pun, AI wajib: + +1. Membaca file ini. +2. Membaca `docapi/README.md` dan `docapi/index.md`. +3. Memahami arsitektur yang ada (section di bawah). +4. Memastikan tidak ada konflik dengan keputusan sebelumnya. +5. Memperbarui dokumentasi setelah implementasi selesai. + +**Implementasi tanpa dokumentasi dianggap belum selesai.** + +--- + +## Ringkasan Proyek + +| Item | Nilai | +|------|-------| +| Nama | Geonet Console | +| URL Production | https://console.gisportal.id | +| Framework | Laravel 12 (PHP 8.3) | +| Database App | PostgreSQL Docker (`databaselist_app`) | +| Database Audit | PostgreSQL Docker (`databaselist_audit`) | +| Auth | LDAP Active Directory (`10.100.1.40`) | +| Storage Avatar | QNAP QuObjects OSS (S3-compatible) | +| Deploy | Docker → Nginx reverse proxy `10.100.1.24` | +| Stack path | `/opt/stacks/geonet-console` | +| Port host | `127.0.0.1:8091` → container port `80` | +| Repo path | `server-connection/geonet-console/` | + +--- + +## Arsitektur Ringkas + +``` +Browser / my.gisportal.id (Next.js) + │ + ▼ +Nginx Reverse Proxy (10.100.1.24) + ├── console.gisportal.id → geonet-console:80 (8091) + └── file.gisportal.id/super-apps/ → QNAP OSS (10.100.1.10:8010) + │ + ▼ +geonet-console Container (PHP 8.3 + Laravel 12) + ├── PHP-FPM + Nginx (dalam container via supervisord) + ├── PostgreSQL audit-postgres (container saudara) + ├── Active Directory LDAP (10.100.1.40) + ├── SQL Server (10.100.1.25:1433) + ├── Ollama AI (10.100.1.26:11434) + ├── QNAP OSS S3 (10.100.1.10:8010) — avatar storage + └── SMTP (sc138.idcloudhosting.cloud:465) +``` + +--- + +## Struktur Kode Penting + +``` +geonet-console/ +├── context-index.md ← FILE INI +├── DOCKGE.md ← Ringkasan deploy & env vars +├── .env.example ← Template env vars (WAJIB BACA sebelum deploy) +├── compose.yaml ← Docker Compose (services, volumes, env) +├── Dockerfile ← Multi-stage build PHP 8.3 + extensions +├── docker/ +│ └── entrypoint.sh ← Startup: migrate, cache, OAuth keys +├── app/ +│ ├── Http/Controllers/Api/V1/ ← Semua API controllers +│ ├── Models/ ← Eloquent models +│ ├── Services/ ← Business logic (LDAP, Auth, DB, dll.) +│ └── Support/ ← ApiActor, helpers +├── config/ +│ ├── filesystems.php ← Disk 'oss' (QNAP OSS S3) +│ └── database.php ← Koneksi pgsql, audit, project_search +├── routes/ +│ └── api.php ← Semua route API v1 +├── database/ +│ └── migrations/ ← Migrasi DB (app, audit, project_search) +└── docapi/ ← Dokumentasi API (WAJIB BACA) + ├── README.md + ├── index.md ← Daftar semua endpoint + ├── authentication.md + └── services/ ← Dokumentasi per service +``` + +--- + +## Informasi Infrastruktur Kritis + +| Role | IP | SSH Command | +|------|----|-------------| +| Reverse Proxy (deploy target) | 10.100.1.24 | `ssh -m hmac-sha1 root@10.100.1.24 -p 22` | +| Database SQL Server | 10.100.1.25 | `ssh -m hmac-sha1 root@10.100.1.25 -p 22` | +| Active Directory / LDAP | 10.100.1.40 | `ssh -m hmac-sha1 Administrator@10.100.1.40 -p 22` | +| NAS QNAP (OSS storage) | 10.100.1.10 | `ssh -i "$env:USERPROFILE\.ssh\id_ed25519" -o IdentitiesOnly=yes -m hmac-sha1 admin@10.100.1.10 -p 22` | +| Ollama AI | 10.100.1.26 | `ssh -i "$env:USERPROFILE\.ssh\id_rsa_geonet_laptop" -o IdentitiesOnly=yes -m hmac-sha1 root@10.100.1.26 -p 22` | + +> AI **wajib minta persetujuan user** sebelum menjalankan perintah SSH. + +**Stack path di server:** `/opt/stacks/geonet-console/` +**Nginx config:** `/etc/nginx/conf.d/production/geonet-console.conf` +**Env file:** `/opt/stacks/geonet-console/.env` + +--- + +## Database Connections + +| Connection name | Driver | Host | Database | Dipakai untuk | +|----------------|--------|------|----------|----------------| +| `pgsql` (default) | PostgreSQL | `audit-postgres` (container) | `databaselist_app` | App metadata, user meta, tokens, settings | +| `audit` | PostgreSQL | `audit-postgres` (container) | `databaselist_audit` | Audit log aktivitas | +| `project_search` | PostgreSQL | `10.100.1.25` | `geonet_project_search` | Indeks AI project search | +| `mssql` | SQL Server | `10.100.1.25:1433` | `master` | Database registry (read) | + +> Connection name dipilih via env var `DB_CONNECTION=pgsql`. Jangan ubah ke `sqlite` — migration harus tetap ke PostgreSQL. + +--- + +## Object Storage (Avatar) — QNAP OSS + +| Item | Nilai | +|------|-------| +| Disk Laravel | `oss` (`config/filesystems.php`) | +| Driver | `s3` dengan `use_path_style_endpoint=true` | +| Endpoint internal | `http://10.100.1.10:8010` | +| Bucket | `super-apps` | +| URL publik avatar | `https://file.gisportal.id/super-apps/avatars/` | +| Nginx proxy | `/etc/nginx/conf.d/nas.conf` → `location /super-apps/` | +| ACL bucket | Public-read (`X-Container-Read: .r:*,.rlistings`) | + +> ⚠️ **Secret Key:** Nilai `OSS_SECRET_ACCESS_KEY` di `.env.example` adalah placeholder. Nilai yang benar ada di `/opt/stacks/geonet-console/.env` server. Jangan commit secret key ke repo. +> +> ⚠️ **Format Access Key:** `super-apps:0Jq7KbF31eJzd4k3LSXN` (format: `:`). + +--- + +## Auth Flow + +``` +POST /api/v1/auth/login + → LdapAuthService::attempt() # bind ke AD 10.100.1.40 + → LdapJwtService::generate() # buat JWT payload (username, groups, ttl) + → return { token, expires_at } + +GET /api/v1/* dengan Bearer token + → ApiAuthService::resolve() # decode JWT / lookup API Token + → ApiActor { identifier, type, groups, scopes } + → Controller menggunakan ApiActor +``` + +**LDAP Bind DN:** `Administrator@gisportal.id` +**LDAP Base DN:** `DC=gisportal,DC=id` +**Admin groups:** `Domain Admins`, `Administrators`, `Enterprise Admins` + +> ⚠️ `LDAP_BIND_PASSWORD` di `.env.example` adalah placeholder `change-me`. Nilai asli tersimpan di `.env` server. + +--- + +## API Kritis + +**Base URL:** `https://console.gisportal.id/api/v1` +**Auth header:** `Authorization: Bearer ` + +| Endpoint | Deskripsi | +|----------|-----------| +| `POST /auth/login` | Login LDAP → JWT | +| `POST /auth/refresh` | Refresh JWT | +| `GET /me` | Info user + avatar URL | +| `PUT /me/avatar` | Upload avatar (base64, maks 300KB) | +| `GET /ldap/users` | List user Active Directory | +| `GET /databases` | List database registry | +| `GET /service-tokens` | List service tokens | +| `POST /project-search/ask` | Query AI natural language | + +> Detail lengkap → `docapi/index.md` dan `docapi/services/` + +--- + +## Cara Deploy + +```powershell +# 1. Build archive (dari Windows) +tar -czf "$env:TEMP\geonet-console.tar.gz" ` + --exclude="vendor" --exclude=".git" --exclude="node_modules" ` + -C "D:\Project\app on git\server-connection\geonet-console" . + +# 2. Upload ke server +Start-Process -FilePath "cmd.exe" -ArgumentList ` + '/c ssh -m hmac-sha1 root@10.100.1.24 -p 22 "cat > /tmp/geonet-console.tar.gz" < "%TEMP%\geonet-console.tar.gz"' ` + -Wait -NoNewWindow + +# 3. Extract & deploy +ssh -m hmac-sha1 root@10.100.1.24 -p 22 " + mkdir -p /opt/stacks/geonet-console && + tar -xzf /tmp/geonet-console.tar.gz -C /opt/stacks/geonet-console && + rm /tmp/geonet-console.tar.gz && + cd /opt/stacks/geonet-console && + docker compose up -d --build --force-recreate +" +``` + +> ⚠️ **JANGAN overwrite `.env`** saat deploy — file `.env` di server berisi credentials production yang tidak ada di repo. +> ⚠️ Extract **tanpa** `--strip-components` agar struktur folder tetap benar. + +--- + +## Env Vars Kritis + +| Variable | Keterangan | Default aman? | +|----------|------------|---------------| +| `APP_KEY` | Laravel encryption key | Auto-generate jika kosong | +| `LDAP_BIND_PASSWORD` | Password AD bind account | ❌ wajib diisi | +| `APP_DB_PASSWORD` | Password PostgreSQL app | ❌ wajib diisi | +| `OSS_SECRET_ACCESS_KEY` | QNAP OSS secret key | ❌ wajib diisi | +| `MSSQL_PASSWORD` | SQL Server password | ❌ wajib diisi | +| `MAIL_PASSWORD` | SMTP password | ❌ wajib diisi | +| `DB_CONNECTION` | Driver database default | Harus `pgsql` | + +> Lihat `.env.example` untuk daftar lengkap. + +--- + +## Models & Services Utama + +### Models (`app/Models/`) +| Model | Tabel | Keterangan | +|-------|-------|------------| +| `LdapUserMeta` | `ldap_user_meta` | Metadata user LDAP (avatar, settings) | +| `LdapGroupMeta` | `ldap_group_meta` | Metadata group LDAP | +| `DatabaseConnection` | `database_connections` | Registry database | +| `ServiceToken` | `service_tokens` | Token antar-service | +| `AuditLog` | `audit_logs` | Log aktivitas (DB audit) | +| `ApiToken` | `api_tokens` | Personal API Token user | + +### Services (`app/Services/`) +| Service | Tanggung Jawab | +|---------|---------------| +| `LdapAuthService` | Login via LDAP, validasi grup admin | +| `LdapUserService` | CRUD user Active Directory | +| `LdapGroupService` | CRUD group Active Directory | +| `LdapJwtService` | Generate & decode JWT | +| `ApiAuthService` | Resolve token → `ApiActor` | +| `AuditLogService` | Tulis log ke DB audit | +| `DatabaseConnectionManager` | Test & manage koneksi DB external | +| `ProjectSearchService` | Indeks & query AI project search | +| `OllamaService` | Koneksi ke Ollama (LLM) | +| `AgentTokenSyncService` | Sync token dari GeoNetAgent DB | + +--- + +## Dokumentasi API + +**Lokasi:** `docapi/` + +| File | Isi | +|------|-----| +| `README.md` | Aturan dan checklist API | +| `index.md` | **Daftar semua endpoint** (baca ini dulu) | +| `authentication.md` | Panduan auth (JWT, API Token, scope) | +| `common-response.md` | Format response standar | +| `common-error.md` | Kode error standar | +| `integration-guide.md` | Panduan integrasi service | +| `services/auth/` | Login, refresh, token guide | +| `services/ldap/` | Users & groups LDAP | +| `services/databases/` | Database registry | +| `services/service-tokens/` | Token management | +| `services/project-search/` | AI search | + +--- + +## Checklist Sebelum Implementasi + +AI wajib memastikan: + +- [ ] Sudah membaca `context-index.md` (file ini) +- [ ] Sudah membaca `docapi/README.md` dan `docapi/index.md` +- [ ] Sudah membaca `DOCKGE.md` jika terkait deploy/env +- [ ] Sudah memahami `config/database.php` jika terkait DB +- [ ] Sudah memahami `config/filesystems.php` jika terkait storage +- [ ] Tidak ada konflik dengan arsitektur yang sudah ada + +--- + +## Checklist Setelah Implementasi + +AI wajib memperbarui: + +- [ ] `docapi/index.md` — jika ada endpoint baru/berubah +- [ ] `docapi/services//` — dokumentasi endpoint detail +- [ ] `context-index.md` — jika ada perubahan arsitektur/infrastruktur +- [ ] `.env.example` — jika ada env var baru +- [ ] `mysupperapps_FE_PWA/docs/project/development-log.md` — catat perubahan +- [ ] `mysupperapps_FE_PWA/CHANGELOG.md` — jika perubahan mempengaruhi FE + +--- + +## Known Issues & Catatan Penting + +- **`project_search` DB:** Connection ke `10.100.1.25` — jika server external tidak reachable, migration akan gagal saat startup. Error ini tidak mempengaruhi fungsi utama app. +- **`DB_CONNECTION=pgsql`** di `compose.yaml` override nilai di `.env`. Jangan ubah ke `sqlite`. +- **OAuth keys** (`storage/oauth-private.key`) di-generate otomatis saat pertama kali container start. Disimpan di Docker volume `app_storage`. +- **Bucket OSS** harus tetap `public-read`. Jika ACL ter-reset, jalankan script Swift API untuk set ulang `X-Container-Read: .r:*,.rlistings`. +- **LDAP_BIND_PASSWORD** di `.env.example` adalah placeholder — selalu cek `/opt/stacks/geonet-console/.env` di server untuk nilai yang benar. + +--- + +## Penutup + +Repository ini dirancang agar: + +- Developer baru dapat memahami proyek dengan cepat. +- AI Agent mana pun dapat melanjutkan pekerjaan tanpa kehilangan konteks. +- Seluruh pengetahuan proyek tersimpan di dalam repository. +- Dokumentasi selalu selaras dengan implementasi. + +**Repository adalah sumber kebenaran utama.** + +Jika terjadi perbedaan antara implementasi dan dokumentasi, AI wajib memperbarui dokumentasi hingga keduanya konsisten.