gDown Inicio rápido

Inicio rápido: de cero a una primera consulta en cinco minutos: arranque gDown con Docker, consúltelo por HTTP y conéctese desde Java o Python con el driver oficial de Neo4j. Nada de esto necesita las fuentes de gDown: cada archivo lo sirve este sitio.

1. Arrancar gDown

Docker es el camino más corto: la imagen está firmada, se ejecuta sin root y no tiene contraseña por defecto (el comando crea una en secrets/admin_password). Instalación en un servidor, clúster y OpenShift: página de instalación.

mkdir gdown && cd gdown
curl -fsSLO https://gdown.gluonify.io/docker/docker-compose.yml
mkdir -p secrets && openssl rand -base64 24 | tr -d '\n' > secrets/admin_password && chmod 644 secrets/admin_password
docker compose up -d && docker compose ps      # wait for "healthy"

2. Una primera consulta por HTTP

POST /db/{base}/query recibe un cuerpo JSON: statement y parameters (escritos $name en Cypher). La respuesta da columns, un array por fila, y stats. La base por defecto es neo4j; la autenticación Basic con la cuenta de administrador basta para esta primera prueba, y el contrato OpenAPI está en /q/openapi (Swagger UI en /rest).

PASSWORD="$(cat secrets/admin_password)"
curl -s -u "neo4j:$PASSWORD" -H 'Content-Type: application/json' localhost:8080/db/neo4j/query \
  -d '{"statement":"CREATE (a:Person {name: $name})-[:KNOWS]->(:Person {name: \"Bob\"}) RETURN a.name","parameters":{"name":"Ann"}}'
curl -s -u "neo4j:$PASSWORD" -H 'Content-Type: application/json' localhost:8080/db/neo4j/query \
  -d '{"statement":"MATCH (p:Person)-[:KNOWS]->(f) RETURN p.name, f.name"}'
# {"columns":["p.name","f.name"],"rows":[["Ann","Bob"]],"stats":{...}}

3. Una cuenta y un token para su aplicación

No distribuya la contraseña de administrador. Cree un usuario local con el rol writer (o reader) y luego un token de API revocable: se muestra una sola vez, se acepta como token bearer por HTTP, MCP y Bolt, y como contraseña de ese mismo usuario en los drivers. Ejecute estas instrucciones en la consola web (http://localhost:8080) o con cypher-shell.

CREATE USER app SET PASSWORD 'change-me' CHANGE NOT REQUIRED;
GRANT ROLE writer TO app;
CREATE API TOKEN app_token FOR USER app EXPIRES IN '90d';   -- shown once: gdt_… ; later: SHOW API TOKENS, DROP API TOKEN app_token

4. Java con el driver oficial de Neo4j

gDown habla Bolt 5.0 a 5.4: los drivers oficiales funcionan sin cambios (Java, Python, JavaScript, Go, .NET), igual que Neo4j-OGM y Spring Data Neo4j. neo4j:// envía las escrituras al líder y las lecturas a los seguidores; bolt:// habla con un miembro. Las transacciones gestionadas se reintentan durante un cambio de líder.

Maven

<dependency>
  <groupId>org.neo4j.driver</groupId>
  <artifactId>neo4j-java-driver</artifactId>
  <version>5.28.15</version>
</dependency>

Gradle (DSL Kotlin)

implementation("org.neo4j.driver:neo4j-java-driver:5.28.15")

Java: GDOWN_TOKEN contiene el token del paso 3, nunca escrito en el código

import org.neo4j.driver.*;
import java.util.Map;

try (Driver driver = GraphDatabase.driver("neo4j://localhost:7687", AuthTokens.basic("app", System.getenv("GDOWN_TOKEN")))) {
    driver.verifyConnectivity();
    try (Session session = driver.session(SessionConfig.forDatabase("neo4j"))) {
        session.executeWrite(tx -> tx.run("CREATE (:Person {name: $n})", Map.of("n", "Ada")).consume());
        var names = session.executeRead(tx -> tx.run("MATCH (p:Person) RETURN p.name AS name ORDER BY name").list(r -> r.get("name").asString()));
        System.out.println(names);
    }
}

5. Python

La misma API de driver desde Python: basta el paquete neo4j, con el usuario y el token del paso 3.

pip install neo4j
python3 - <<'PY'
import os
from neo4j import GraphDatabase
with GraphDatabase.driver("neo4j://localhost:7687", auth=("app", os.environ["GDOWN_TOKEN"])) as driver:
    driver.verify_connectivity()
    with driver.session(database="neo4j") as s:
        s.execute_write(lambda tx: tx.run("CREATE (:Person {name: $n})", n="Ada").consume())
        print(s.execute_read(lambda tx: [r["name"] for r in tx.run("MATCH (p:Person) RETURN p.name AS name ORDER BY name")]))
PY

En la plataforma Gluonify

Una aplicación desplegada en Gluonify no configura gDown. Declare gdown en uses (o deje que el build lo deduzca del driver Neo4j presente en el classpath de ejecución): la plataforma inyecta GLUONIFY_GDOWN_BOLT_URL y GLUONIFY_GDOWN_CA_FILE antes del arranque, Bolt bajo TLS en la red interna, y la cuenta viene de los secretos de la aplicación.

gluonify.json (solo si el driver no está en el classpath de ejecución)

{ "uses": ["gdown"] }

Leer las variables inyectadas (driver Java)

// On Gluonify, the platform sets GLUONIFY_GDOWN_BOLT_URL (bolt+s://…:7687) and GLUONIFY_GDOWN_CA_FILE (the internal CA, PEM) before start.
Config config = Config.builder().withTrustStrategy(Config.TrustStrategy.trustCustomCertificateSignedBy(new java.io.File(System.getenv("GLUONIFY_GDOWN_CA_FILE")))).build();
Driver driver = GraphDatabase.driver(System.getenv("GLUONIFY_GDOWN_BOLT_URL"), AuthTokens.basic(user, password), config);

Desde su puesto, la CLI de Gluonify le conecta a su zona en el navegador; el SDK resuelve después los servicios de la plataforma para una ejecución local.

java -jar gluonify-plasma-cli-0.7.0.jar login <your-zone>   # once, in the browser (PKCE); then: mvn quarkus:dev

Para continuar

  • Consola web: consultas, vista del grafo, modelo de datos y estado del clúster, en http://localhost:8080.
  • Asistentes de IA: el servidor MCP en /mcp, los índices vectoriales y de texto completo, y la memoria de sus repositorios.
  • Un clúster de tres miembros, TLS mutuo, OpenShift y Microsoft Entra ID: la página de instalación.
  • Lo que se admite: cobertura openCypher, funciones Bolt y HTTP, límites, en la página de comparativa.
  • Documentación de la imagen en Docker Hub: variables, volúmenes, actualizaciones, límites.

Puertos: 8080 para HTTP (API, consola, Swagger UI) y 7687 para Bolt. Un token nunca va en una URL, un registro ni un repositorio.