graph-go è un mapper di infrastruttura CLI-first. Scopre automaticamente la tua infrastruttura connettendosi al demone Docker, ispezionando i container in esecuzione e sondando database e servizi di storage. L'interfaccia utente è servita dal backend e riflette lo stato reale del backend — nessun inventario manuale necessario.

Label Docker

graph-go rispetta un piccolo insieme di label container graphgo.* (impostale su qualsiasi container che vuoi controllare):

Usale per recuperare container classificati male, puntare graph-go verso un DSN personalizzato o nascondere un container dal grafico senza rimuoverlo.

Avvio rapido — provalo in 30 secondi

Avvia lo stack demo preconfigurato con il CLI. Questo è il modo più veloce per vedere graph-go in un ambiente realistico ed è il percorso di onboarding previsto per i nuovi utenti:

git clone https://github.com/guilherme-grimm/graph-go.git
cd graph-go
go run ./cmd/app demo

Apri http://localhost:8080. Il comando viene eseguito in primo piano tramite Docker Compose. Premi Ctrl+C per fermare la sessione.

La prima esecuzione può richiedere diversi minuti su una macchina "fredda" perché Docker potrebbe dover scaricare le immagini di base e costruire le immagini demo locali. Le esecuzioni successive sono molto più veloci.

Lo stack demo richiede che queste porte host siano libere: 8080, 5432, 27017, 9000 e 9001.

Se hai bisogno di un abbattimento esplicito in seguito:

docker compose -f docker-compose.demo.yml down

Esegui contro il tuo stack

Un container, una porta. Monta il socket Docker in sola lettura e graph-go scopre automaticamente tutto ciò che è in esecuzione sull'host:

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

graph-go legge solo dal socket Docker. Il flag :ro lo impone — mantienilo.

Apri http://localhost:8080. L'auto-scoperta gestisce i container Docker e (quando è presente un kubeconfig o un account di servizio in-cluster) le risorse Kubernetes senza alcun file di configurazione.

Per servizi che vivono al di fuori di Docker/Kubernetes (database remoti, servizi cloud gestiti), monta un file di configurazione — vedi Configurazione.

Binario precompilato

Singolo binario autonomo — l'interfaccia utente è inclusa, ma il punto di ingresso è sempre il CLI.

# Linux amd64 (richiede il CLI di GitHub; cerca nella sezione Releases altre piattaforme)
gh release download --repo guilherme-grimm/graph-go --pattern 'graph-go_*_linux_amd64.tar.gz' --clobber
tar xzf graph-go_*_linux_amd64.tar.gz
./graph-go serve   # oppure `./graph-go` - fa la stessa cosa

Apri http://localhost:8080. Altre piattaforme nella pagina Releases.

Comandi

Flag globali (si applicano a ogni sottocomando): --config, --log-level, --log-format. Vedi graph-go <comando> --help per la superficie completa di ogni comando.

Flusso tipico:

1. graph-go demo per una dimostrazione realistica locale.
2. graph-go serve per eseguire sulla tua infrastruttura.
3. graph-go scan per automazione una tantum, esportazioni o controlli CI.

Porte

Configurazione

L'auto-scoperta è la via maestra. Monta il socket Docker e/o esegui all'interno di un cluster Kubernetes — graph-go scopre la tua infrastruttura senza bisogno di file di configurazione.

Usa il file di configurazione YAML (conf/config.yaml) solo come valvola di sfogo per servizi non raggiungibili tramite scoperta — database remoti, servizi cloud gestiti, endpoint esterni. Vedi conf/config.sample.yaml per lo schema completo — esempi per ogni adapter e ogni blocco di configurazione (server, docker, kubernetes, connections).

Per usare un file di configurazione con il comando Docker sopra:

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $(pwd)/conf/config.yaml:/app/conf/config.yaml:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

Uso autorizzato solo: graph-go è per visualizzare infrastrutture di tua proprietà o per cui hai permesso di accesso. Non puntarlo su sistemi senza autorizzazione.

Panoramica dell'Architettura

Backend (Go)

                          ┌─────────────────────────────────────┐
                          │         Discoverer Interface         │
                          │  Discover() · Watch() · Close()     │
                          └──────────┬──────────┬───────────────┘
                                     │          │
                          ┌──────────▼──┐  ┌────▼──────────────┐
                          │   Docker    │  │   Kubernetes       │
                          │  Discoverer │  │   Discoverer       │
                          │ (containers,│  │ (informers, pods,  │
                          │  classify,  │  │  deployments,      │
                          │  events)    │  │  services, health) │
                          └──────┬──────┘  └────┬──────────────┘
                                 │               │
                          ┌──────▼───────────────▼──────┐
                          │  Parallel Discovery + Merge  │
                          │  (concatenate ServiceInfo)   │
                          └──────────────┬──────────────┘
                                         │
Config (YAML) ──→ YAML Merge ───────────▶│
                                         ▼
                          ┌─────────────────────────────┐
                          │     Adapter Registry         │
                          │  ├─ PostgreSQL  → Tables + FK│
                          │  ├─ MongoDB    → Collections │
                          │  ├─ MySQL      → Tables + FK │
                          │  ├─ Redis      → Keyspaces   │
                          │  ├─ Elasticsearch → Indices   │
                          │  ├─ S3         → Buckets      │
                          │  └─ HTTP       → Health + deps│
                          │                               │
                          │  + Topology (K8s nodes/edges) │
                          └──────────────┬───────────────┘
                                         ▼
                          Graph Model (Nodes + Edges)
                                         ▼
                          REST API + WebSocket (Real-time)

Componenti Chiave:

• Discoverer Interface: Contratto uniforme (Discover, Watch, Close) per tutti i backend di scoperta — Docker e Kubernetes vengono eseguiti in parallelo, i risultati sono concatenati
• Docker Discovery: Ispeziona i container, classifica le immagini, estrae credenziali dalle variabili d'ambiente, osserva gli eventi Docker per cambiamenti live della topologia
• Kubernetes Discovery: Usa gli informer di client-go con gestione degli eventi con debounce; scopre Namespaces, Deployments, StatefulSets, DaemonSets, Pods e Services con mappatura dello stato
• Adapters: Implementano l'interfaccia Adapter per sondare database e servizi di storage
• Registry: Gestisce adapter e insiemi di topologia, crea nodi genitore a livello di servizio, aggrega i dati del grafico
• Cache: TTL di 30 secondi con pattern singleflight per evitare il thundering herd
• WebSocket: Stream di aggiornamenti di stato ogni 5 secondi

Frontend (React + TypeScript)

• Layout a corsie: Layout consapevole dei namespace con classificazione delle zone (namespace di sistema, infrastruttura, applicazione)
• Contenitori di gruppo: I namespace K8s vengono renderizzati come riquadri richiudibili tramite il raggruppamento di React Flow
• Ispettore di nodo: Pannello laterale che mostra metadati dettagliati e connessioni
• Hook WebSocket: Aggiornamenti di stato in tempo reale senza polling

Gerarchia dei Nodi

Scoperto da adapter:
  Service Node (postgres/mongodb/s3)
      └─ Database/Bucket Node
          └─ Table/Collection/Prefix Node

Scoperto da Kubernetes:
  Namespace (group container)
      └─ Deployment / StatefulSet / DaemonSet
          └─ Pod
      └─ K8sService ──routes_to──→ Pod

Gli archi rappresentano relazioni (contains, foreign_key, routes_to, ecc.).

Stack Tecnologico

Backend:

• Go 1.25.6
• gorilla/mux (Routing HTTP)
• k8s.io/client-go (Scoperta Kubernetes + informer)
• pgxpool (PostgreSQL)
• mongo-driver v2 (MongoDB)
• go-sql-driver/mysql (MySQL)
• go-redis/v9 (Redis)
• go-elasticsearch/v8 (Elasticsearch)
• AWS SDK v2 (S3)
• coder/websocket (WebSocket)
• testcontainers-go (Test di integrazione)

Frontend:

• TypeScript
• React 19
• @xyflow/react v12 (Visualizzazione grafico)
• Vite (Strumento di build)

Infrastruttura:

• Docker + Docker Compose
• PostgreSQL 17
• MongoDB 7
• MySQL 8
• Redis 7
• Elasticsearch 8
• MinIO (Compatibile S3)

Test

Test Unitari

go test ./...

Viene eseguito senza Docker. Include test di funzioni pure e test degli handler HTTP.

Test di Integrazione

go test -tags=integration -v -timeout=5m ./internal/adapters/...

Richiede Docker. Usa testcontainers-go per avviare istanze di database reali (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) — nessun mock.

Ogni adapter viene testato attraverso la suite di test del contratto (adaptertest.RunContractTests) che valida:

• Ciclo di vita connect/disconnect
• Scoperta di nodi/archi (ID univoci, riferimenti genitore validi, tipi corretti)
• Metriche di stato (chiave status, chiavi richieste)

Esegui i test di un singolo adapter:

go test -tags=integration -v ./internal/adapters/redis/

Tutti i Test

make test  # unit + type-check
go test -tags=integration -timeout=5m ./internal/adapters/...  # integration

Riferimenti API

GET /api/graph

Restituisce l'intero grafico dell'infrastruttura (nodi + archi).

Risposta:

{
  "data": {
    "nodes": [
      {
        "id": "service-postgres",
        "type": "postgres",
        "name": "postgres",
        "metadata": { "adapter": "postgres" },
        "health": "healthy"
      }
    ],
    "edges": [
      {
        "id": "edge-1",
        "source": "service-postgres",
        "target": "pg-mydb",
        "type": "contains",
        "label": "contains"
      }
    ]
  }
}

GET /api/node/{id}

Restituisce i dettagli per un nodo specifico.

GET /api/health

Restituisce lo stato degli adapter (ok/degraded/error).

WS /websocket

Stream di aggiornamenti in tempo reale. Vengono emessi due tipi di messaggio, entrambi incapsulati come { "type": "...", "payload": { ... } }. Non c'è un campo timestamp: i client deducono l'ordine in base all'arrivo.

health_update — inviato per ogni nodo una volta per ciclo (ogni 5s). I nodi di proprietà dell'adapter ottengono lo stato tramite la ricerca dell'adapter; i nodi di topologia (es. risorse Kubernetes) portano lo stato direttamente sul nodo.

{
  "type": "health_update",
  "payload": {
    "nodeId": "service-postgres",
    "health": "healthy"
  }
}

health può essere healthy, degraded, unhealthy.

graph_update — inviato quando l'insieme degli ID dei nodi cambia (un nodo è stato aggiunto o rimosso dalla scoperta). payload è vuoto; i client dovrebbero rifare la richiesta /api/graph.

{
  "type": "graph_update",
  "payload": {}
}

Aggiungere un Nuovo Adapter

1. Crea il pacchetto dell'adapter in internal/adapters/{nome}/
2. Implementa l'interfaccia Adapter:
   root@kitploit:~

   type Adapter interface {
       Connect(config ConnectionConfig) error
       Discover() ([]nodes.Node, []edges.Edge, error)
       Health() (HealthMetrics, error)
       Close() error
   }
   

3. Auto-registrati tramite init() con adapters.RegisterFactory("nome", ...)
4. Aggiungi test di integrazione (obbligatori) — crea {nome}_integration_test.go con:
   • Build tag //go:build integration
   • TestMain usando testcontainers-go per avviare un'istanza reale
   • Inserisci dati rappresentativi
   • Chiama adaptertest.RunContractTests per validare il contratto dell'interfaccia
   • Aggiungi test specifici dell'adapter (filtraggio, formato ID, metadati, ecc.)
5. Importa l'adapter in internal/server/server.go (import vuoto per )

Aggiungere un Nuovo Discoverer

I Discoverer risiedono in internal/discovery/{nome}/ e implementano l'interfaccia Discoverer:

type Discoverer interface {
    Name() string
    Discover(ctx context.Context) ([]ServiceInfo, error)
    Watch(ctx context.Context, onChange func()) error
    Close() error
}

1. Crea il pacchetto discoverer in internal/discovery/{nome}/
2. Implementa l'interfaccia Discoverer — restituisci []ServiceInfo da Discover(). I discoverer che producono topologia (es. K8s) popolano direttamente Nodes/Edges; quelli orientati agli adapter (es. Docker) popolano Config per il bridging con gli adapter.
3. Collega al server in internal/server/server.go — aggiungi una funzione build{nome}Discovery() e chiamala insieme ai discoverer esistenti.
4. Aggiungi test di integrazione con //go:build integration — usa infrastruttura reale (kind/k3d per K8s, testcontainers per altri). Nessun mock.

Vedi CONTRIBUTING.md per indicazioni dettagliate.

Contribuire

Accogliamo con piacere i contributi! Vedi CONTRIBUTING.md per linee guida su:

• Configurazione dell'ambiente di sviluppo
• Convenzioni di stile del codice
• Come aggiungere nuovi adapter
• Invio di pull request

Ambito di Utilizzo ed Etica

Uso Inteso:

• Visualizzare e monitorare infrastrutture di tua proprietà o per cui hai autorizzazione di accesso
• Dashboard DevOps e mappatura della topologia
• Documentazione dell'infrastruttura e onboarding
• Esplorare schemi di database e relazioni

Non Inteso Per:

• Scansione o ricognizione non autorizzata di sistemi
• Test di sicurezza senza permesso esplicito
• Accesso a sistemi che non possiedi o controlli

Gli utenti sono responsabili di assicurarsi di avere la dovuta autorizzazione prima di connettere graph-go a qualsiasi infrastruttura.

Licenza

Questo progetto è distribuito con licenza GNU Affero General Public License v3.0 (AGPL-3.0).

Vedi il file LICENSE per i dettagli. AGPL richiede che le versioni modificate utilizzate su una rete siano anch'esse open-source.

CI/CD & Rilasci

Il progetto usa GitHub Actions per l'integrazione continua e i rilasci automatici.

• CI viene eseguito su ogni push/PR su main — test unitari backend, test di integrazione (testcontainers) e build frontend
• Rilasci vengono attivati da tag di versione (v*) e producono:
  • Binari cross-platform (Linux, macOS, Windows) tramite GoReleaser
  • Immagine Docker singola pubblicata su ghcr.io/guilherme-grimm/graph-go

Per creare un rilascio:

git tag v0.1.0
git push --tags

Roadmap

• Auto-scoperta Docker
• Monitoraggio dello stato dei servizi HTTP
• Adapter MySQL
• Adapter Redis
• Adapter Elasticsearch
• Test di integrazione con testcontainers-go (tutti gli adapter)
• Suite di test del contratto per la conformità dell'interfaccia adapter
• Interfaccia Discoverer (backend di scoperta pluggabili)
• Orchestrator Kubernetes (Namespace, Deployments, StatefulSets, DaemonSets, Pods, Services)
• Osservazione K8s in tempo reale basata su informer con debounce
• Layout a corsie con contenitori di gruppo per namespace
• Bridging degli adapter K8s (classificare pod per immagine, collegare adapter ai database nei pod)
• Osservabilità del flusso (visualizzazione del flusso di dati in tempo reale)
• Trigger di stress integrato (k6 con visualizzazione dell'impatto in tempo reale)

Supporto

• Issue: github.com/guilherme-grimm/graph-go/issues
• Discussioni: github.com/guilherme-grimm/graph-go/discussions

Realizzato con ❤️ per ingegneri DevOps e dell'infrastruttura