gDown Avvio rapido

Avvio rapido: da zero a una prima query in cinque minuti: avviare gDown con Docker, interrogarlo via HTTP, poi connettersi da Java o Python con il driver ufficiale Neo4j. Niente di tutto ciò richiede i sorgenti di gDown: ogni file è servito da questo sito.

1. Avviare gDown

Docker è la via più breve: l'immagine è firmata, gira senza root e non ha alcuna password predefinita (il comando ne crea una in secrets/admin_password). Installazione su un server, cluster e OpenShift: pagina di installazione.

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 prima query via HTTP

POST /db/{database}/query riceve un corpo JSON: statement e parameters (scritti $name in Cypher). La risposta dà columns, un array per riga, e stats. Il database predefinito è neo4j; l'autenticazione Basic con l'account amministratore basta per questa prima prova, e il contratto OpenAPI è su /q/openapi (Swagger UI su /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. Un account e un token per la vostra applicazione

Non distribuite la password di amministratore. Create un utente locale con il ruolo writer (o reader), poi un token API revocabile: mostrato una sola volta, accettato come token bearer su HTTP, MCP e Bolt, e come password dello stesso utente nei driver. Eseguite queste istruzioni nella console 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 il driver ufficiale Neo4j

gDown parla Bolt da 5.0 a 5.4: i driver ufficiali funzionano senza modifiche (Java, Python, JavaScript, Go, .NET), come Neo4j-OGM e Spring Data Neo4j. neo4j:// invia le scritture al leader e le letture ai follower; bolt:// parla con un membro. Le transazioni gestite vengono ritentate durante un cambio di leader.

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 il token del passo 3, mai scritto nel codice

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 stessa API del driver da Python: basta il pacchetto neo4j, con l'utente e il token del passo 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

Sulla piattaforma Gluonify

Un'applicazione distribuita su Gluonify non configura gDown. Dichiarate gdown in uses (o lasciate che il build lo deduca dal driver Neo4j presente nel classpath di esecuzione): la piattaforma inietta GLUONIFY_GDOWN_BOLT_URL e GLUONIFY_GDOWN_CA_FILE prima dell'avvio, Bolt sotto TLS sulla rete interna, e l'account viene dai segreti dell'applicazione.

gluonify.json (solo se il driver non è nel classpath di esecuzione)

{ "uses": ["gdown"] }

Leggere le variabili iniettate (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);

Dalla vostra postazione, la CLI Gluonify vi connette alla vostra zona nel browser; l'SDK risolve poi i servizi della piattaforma per un'esecuzione locale.

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

Per continuare

  • Console web: query, vista del grafo, modello dei dati e stato del cluster, su http://localhost:8080.
  • Assistenti IA: il server MCP su /mcp, gli indici vettoriali e full-text, e la memoria dei vostri repository.
  • Un cluster di tre membri, TLS reciproco, OpenShift e Microsoft Entra ID: la pagina di installazione.
  • Cosa è supportato: copertura openCypher, funzioni Bolt e HTTP, limiti, nella pagina del confronto.
  • Documentazione dell'immagine su Docker Hub: variabili, volumi, aggiornamenti, limiti.

Porte: 8080 per HTTP (API, console, Swagger UI) e 7687 per Bolt. Un token non va mai in un URL, in un log né in un repository.