fix(dev): support HTTPS and Unix socket GDK setups in native dev script

Dmitry Gruzdrequested to merge
fix/native-dev-https-and-socket-support into main

Summary

  • Fix native dev script (gkg-native-dev.sh) to correctly derive GitLab URL from GDK's hostname, port, and https.enabled settings instead of hardcoding http://127.0.0.1:3000
  • Fix PostgreSQL reachability check to detect Unix socket connections (GDK default) instead of only checking TCP
  • Handle stale Linux-specific paths in gdk.example.yml by falling back to $GDK_ROOT/postgresql
  • Add E2E local development checklist to AGENTS.md covering the full setup path from zero to working Knowledge Graph UI
  • Document Siphon prerequisites (TCP PostgreSQL, prometheus port conflict), GitLab config (feature flags, enabled namespaces), and UI access in local-development.md

Problem

mise run dev:check failed on GDK setups with HTTPS enabled (hostname: gdk.test, port: 3443, https.enabled: true) because:

  1. GKG_GITLAB__BASE_URL was always set to http://127.0.0.1:3000 — but Rails uses a Unix socket behind nginx/workhorse on HTTPS setups
  2. PostgreSQL check used nc -z 127.0.0.1 5432 — but GDK defaults to Unix sockets, not TCP
  3. gdk.example.yml has a hardcoded /home/git/gdk/postgresql path that doesn't exist on macOS

Additionally, the docs didn't cover common GDK pitfalls (Siphon needing TCP PostgreSQL, prometheus port 8081 conflicting with Elasticsearch, Knowledge Graph feature flags and namespace enablement).

Verification

Tested the full E2E workflow on a GDK with HTTPS + nginx + Unix socket PostgreSQL:

mise run dev:check   ✅ all checks pass
mise run dev:setup   ✅ graph DB created, schema applied
mise run dev         ✅ all 3 modes start (webserver, indexer, dispatcher)
Siphon replication   ✅ data flows to datalake after fixing TCP + port conflict
GKG indexing         ✅ graph tables populated (users, projects, groups, MRs, edges)
Knowledge Graph UI   ✅ accessible at https://gdk.test:3443/dashboard/orbit
Edited by Dmitry Gruzd

Merge request reports