guilherme-grimm/graph-gosimplemente nodos y grafos
Visualiza tu infraestructura. Sin configuración.
Apunta graph-go a tu stack y obtén un mapa interactivo en vivo de cada base de datos, tabla, servicio y bucket de almacenamiento — con monitoreo de salud en tiempo real.
graph-go es un mapeador de infraestructura orientado a CLI. Descubre automáticamente tu infraestructura conectándose al demonio de Docker, inspeccionando contenedores en ejecución y sondando bases de datos y servicios de almacenamiento. La interfaz de usuario es servida por el backend y refleja el estado real del backend — no se necesita inventario manual.
| Capacidad | Detalles |
|---|---|
| Auto-descubrimiento | Detecta infraestructura a partir de contenedores Docker y clústeres Kubernetes — no se necesita inventario manual |
| Kubernetes | Namespaces, Deployments, StatefulSets, DaemonSets, Pods, Services — con monitoreo en tiempo real basado en informers |
| Docker | Clasifica contenedores en ejecución, extrae credenciales, observa eventos de Docker, respeta las etiquetas graphgo.* para sobrescribir tipo/DSN/tipo-nodo/nombre o ignorar un contenedor |
| PostgreSQL | Tablas, relaciones de claves foráneas, topología de esquemas |
| MongoDB | Bases de datos y colecciones |
| MySQL | Tablas, relaciones de claves foráneas |
| Redis | Keyspaces y distribución de claves |
| Elasticsearch | Índices, salud del clúster, estado de shards |
| S3 / MinIO | Buckets y prefijos de primer nivel |
| Servicios HTTP | Endpoints de salud, mapeo de dependencias entre servicios |
| Salud en tiempo real | Actualizaciones en vivo vía WebSocket cada 5 segundos |
| Grafo interactivo | Disposición en carriles, contenedores de grupo por namespace, panorámica/zoom, filtrado por tipo/salud, búsqueda de nodos |
graph-go respeta un conjunto pequeño de etiquetas de contenedor graphgo.* (configúralas en cualquier contenedor que desees controlar):
| Etiqueta | Efecto |
|---|---|
graphgo.ignore=true | Omitir este contenedor por completo |
graphgo.type=postgres | Forzar el tipo de adaptador (postgres, mongodb, mysql, redis, elasticsearch, s3, http) |
graphgo.dsn=... | Inyectar una cadena de conexión (DSN para postgres/mysql, URI para mongodb; de lo contrario, recurre a dsn) |
graphgo.node-type=gateway | Sobrescribir el tipo de nodo visual (service, gateway, auth, api, queue, cache) |
graphgo.name=... | Sobrescribir el nombre del nodo mostrado en el grafo y usado en IDs de nodo / registros |
Úsalas para rescatar contenedores mal clasificados, apuntar graph-go a un DSN personalizado, u ocultar un contenedor del grafo sin eliminarlo.
Inicia el stack de demostración precargado con la CLI. Esta es la forma más rápida de ver graph-go en un entorno realista y la ruta de incorporación prevista para nuevos usuarios:
git clone https://github.com/guilherme-grimm/graph-go.git
cd graph-go
go run ./cmd/app demo
Abre http://localhost:8080. El comando se ejecuta adjunto mediante Docker Compose. Presiona Ctrl+C para detener la sesión adjunta.
La primera ejecución puede tardar varios minutos en una máquina fría porque Docker puede necesitar descargar imágenes base y construir las imágenes locales de demostración. Las ejecuciones posteriores son mucho más rápidas.
El stack de demostración espera que estos puertos del host estén libres: 8080, 5432, 27017, 9000 y 9001.
Si necesitas una limpieza explícita después:
docker compose -f docker-compose.demo.yml down
Un contenedor, un puerto. Monta el socket de Docker en modo solo lectura y graph-go descubre automáticamente todo lo que se ejecuta en el 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 solo lee del socket de Docker. La bandera
:rolo impone — mantenla.
Abre http://localhost:8080. El auto-descubrimiento maneja los contenedores Docker y (cuando hay un kubeconfig o una cuenta de servicio dentro del clúster) los recursos de Kubernetes sin necesidad de archivo de configuración.
Para servicios que viven fuera de Docker/Kubernetes (bases de datos remotas, servicios gestionados en la nube), monta un archivo de configuración — consulta Configuración.
Binario único autocontenido — la interfaz de usuario está incrustada, pero el punto de entrada sigue siendo la CLI.
# Linux amd64 (requiere GitHub CLI; consulta Releases para otras plataformas)
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 # o simplemente `./graph-go` — es lo mismo
Abre http://localhost:8080. Otras plataformas en la página de Releases.
| Comando | Qué hace |
|---|---|
graph-go demo | Inicia el stack de demostración Docker Compose precargado desde el repositorio y transmite su salida en primer plano. |
graph-go serve | Inicia el servidor HTTP con auto-descubrimiento y actualizaciones en vivo (predeterminado — igual que ejecutar sin argumentos). |
graph-go scan | Ejecuta el descubrimiento una vez y emite el grafo como JSON a stdout. Útil para canalizar a jq, comprobaciones CI o exportaciones puntuales. |
graph-go version | Imprime versión, commit y fecha de compilación. |
graph-go --health-check | Verifica el endpoint local /health y sale con 0/1. Usado por el HEALTHCHECK del contenedor; no para uso interactivo. |
Banderas globales (aplican a todos los subcomandos): --config, --log-level, --log-format. Consulta graph-go <comando> --help para la superficie completa por comando.
Flujo típico:
graph-go demo para un recorrido local realista.graph-go serve para ejecutar contra tu propia infraestructura.graph-go scan para automatización puntual, exportaciones o comprobaciones CI.| Puerto | Propósito |
|---|---|
8080 | graph-go (UI + API + WebSocket — producción) |
5173 | Servidor de desarrollo Vite (solo desarrollo — consulta CONTRIBUTING.md) |
9001 | Consola MinIO (solo stack de demostración) |
El auto-descubrimiento es el camino. Monta el socket de Docker y/o ejecuta dentro de un clúster de Kubernetes — graph-go descubre tu infraestructura sin necesidad de archivo de configuración.
Usa la configuración YAML (conf/config.yaml) solo como una vía de escape para servicios que no son alcanzables mediante descubrimiento — bases de datos remotas, servicios gestionados en la nube, endpoints externos. Consulta conf/config.sample.yaml para el esquema completo — ejemplos para cada adaptador y cada bloque de configuración (server, docker, kubernetes, connections).
Para usar un archivo de configuración con el Docker run anterior:
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 autorizado únicamente: graph-go es para visualizar infraestructura que posees o para la que tienes permiso de acceso. No lo apuntes a sistemas sin autorización.