rbsetiawan
/
LDAPWeb
1
0
Fork 0
Code Issues 2 Pull Requests Projects Releases Wiki Activity
GeoNetAgent, LDAPWeb, server-audit, server-connection
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
24 Commits
1 Branch
0 Tags
19 MiB
 
 
 
 
 
 
Tree: ad9fbc69c8
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ad9fbc69c8'
${ noResults }
LDAPWeb/server-connection/geonet-console/context-index.md

13 KiB
Raw Blame History Escape

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

# 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.