rbsetiawan
/
LDAPWeb
1
0
Fork 0
Code Issues 2 Pull Requests Projects Releases Wiki Activity
Browse Source

docs: add context-index.md for server-connection and geonet-console

master
Budi Setiawan 3 weeks ago
parent
b88563ea5c
commit
2579826cd9
2 changed files with 442 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 91
      server-connection/context-index.md
  2. 351
      server-connection/geonet-console/context-index.md

91
server-connection/context-index.md
Unescape View File

@ -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)

351
server-connection/geonet-console/context-index.md
Unescape View File

@ -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/<filename>` |
| 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: `<storage-space>:<key-id>`).
---
## 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 <token>`
| 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/<service>/` — 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.
Write Preview
Loading…
Cancel
Save