gDown Installazione

gDown si installa da solo, su una macchina o in cluster, con un unico script. Lo script si limita a verificare e poi installare: controlla un manifesto firmato (Ed25519) e lo SHA-256 del binario prima di scrivere qualsiasi cosa.

gDown diventa un servizio systemd (utente gluonify-gdown, dati in /var/lib/gluonify-gdown). Un primo nodo avvia un nuovo cluster di un solo membro; la password di amministratore generata è conservata in un file leggibile solo da root.

Eseguite il primo comando sulla prima macchina. Il suo token di cluster è in /etc/gluonify-gdown/gdown.env (GLUONIFY_GDOWN_AUTH_TOKEN): copiatelo, poi eseguite l'ultimo comando su ciascuna delle altre macchine, con --seed che indica il primo nodo. Il token passa dall'ambiente, mai come argomento. Il nuovo membro si configura a partire dal primo nodo ed entra nel cluster. Tre membri continuano a funzionare quando uno va perso.

Opzioni

  • --node-id: nome del membro (predefinito: il nome della macchina).
  • --advertise-host: l'indirizzo con cui gli altri membri raggiungono questo (predefinito: il nome della macchina).
  • --seed: URL di un membro di un cluster esistente; da omettere sul primo nodo.
  • --data-dir: cartella dei dati (predefinita /var/lib/gluonify-gdown).
  • --version: versione da installare (predefinita: l'ultima).
  • --key-sha256: impronta della chiave di pubblicazione; lo script rifiuta qualsiasi altra chiave.

Porte

8080 (HTTP: API, console web), 7687 (Bolt) e 9000 (Raft, solo tra membri). Aprite 9000 tra le macchine di un cluster e, per i vostri client, nulla più di 8080 e 7687.

Docker

L’immagine pubblica gluonify/gdown esegue l’eseguibile nativo su Red Hat UBI 9 micro (dalla 0.6.1), per linux/amd64 e linux/arm64: utente non root (uid 10001, o qualsiasi uid del gruppo 0, come li assegna OpenShift), dati nel volume /data, file system radice in sola lettura, controllo di salute svolto dall’eseguibile stesso (niente curl nell’immagine). Funziona senza modifiche con la politica restricted-v2 di OpenShift; uno StatefulSet di tre membri è in questa pagina. Non ha una password predefinita e non si avvia senza la password dell’amministratore iniziale (preferibilmente in un file, un segreto Docker, o nell’ambiente) o un provider OpenID Connect. Dalla 0.6.0 l’eseguibile è costruito da Oracle GraalVM 25 con ottimizzazione guidata dal profilo (PGO); le parti di Oracle GraalVM che contiene sono ridistribuite gratuitamente secondo i GraalVM Free Terms and Conditions (GFTC), il cui testo è incluso nell’immagine in /licenses.

Tre membri con TLS reciproco (Docker Compose)

L’esempio Compose avvia tre membri con TLS reciproco su Raft tra di loro, HTTPS per la console e l’API, e Bolt su TLS. Due script generano certificati di prova e segreti casuali; in produzione usate la vostra autorità di certificazione.

  • Segreti: la password dell’amministratore iniziale può essere data direttamente in GLUONIFY_GDOWN_AUTH_LOCAL_INITIAL_ADMIN_PASSWORD, ma è consigliato GLUONIFY_GDOWN_AUTH_LOCAL_INITIAL_ADMIN_PASSWORD_FILE (un file, ad esempio un segreto Docker), perché l’ambiente compare in docker inspect; lo stesso vale per il token di servizio, con GLUONIFY_GDOWN_AUTH_TOKEN_FILE.
  • Senza TLS tra i membri il cluster funziona, ma Raft viaggia in chiaro: gDown registra un avviso all’avvio e a ogni adesione. Il TLS reciproco è la configurazione raccomandata.
  • Volumi: /data (basi e log Raft, da conservare) e /var/lib/gdown/native, dove la libreria TLS viene estratta (deve consentire l’esecuzione, a differenza di un /tmp noexec).
  • Le immagini sono firmate con cosign con la chiave di Gluonify e includono uno SBOM e un’attestazione di provenienza; un aggiornamento sostituisce un membro alla volta.

OpenShift e Kubernetes

L’immagine funziona senza modifiche sotto la politica restricted-v2 di OpenShift: uid casuale nel gruppo 0, nessuna capability, file system radice in sola lettura. Lasciate runAsUser vuoto (OpenShift lo sceglie e il suo fsGroup rende scrivibile il volume): anyuid non serve. Create il secret con la password di amministratore e il token di servizio, poi applicate il manifesto: un Service headless e uno StatefulSet di tre membri in cui gdown-0 avvia il cluster e gli altri lo raggiungono.

Raft viaggia in chiaro tra i membri: aggiungete le variabili TLS dell’esempio Compose del cluster per cifrarlo. HTTP passa da una Route, Bolt da un Service LoadBalancer (una Route porta solo HTTP); non esponete mai la porta 9000. Verificato sotto Docker con uid casuali del gruppo 0, non ancora su un cluster OpenShift.

Accesso con Microsoft Entra ID

gDown accetta i token di accesso di Entra ID su HTTP, WebSocket e Bolt, e la sua console fa accedere le persone con Entra ID (codice di autorizzazione con PKCE). I diritti vengono dai ruoli applicazione, nel claim roles.

  1. Registrate l’API (tenant singolo) e impostate accessTokenAcceptedVersion a 2 nel suo manifest, per ottenere token v2.
  2. Esponete un’API: URI ID applicazione api://<api-client-id> e un ambito gdown.access, che i client chiedono per ottenere un token destinato a gDown.
  3. Create i ruoli applicazione gDown.Reader, gDown.Writer e gDown.Admin; assegnateli a utenti o gruppi, e ai demoni come autorizzazioni applicazione.
  4. Registrate la console come applicazione a pagina singola (PKCE, senza segreto) con l’indirizzo della console come URI di reindirizzamento, e datele l’autorizzazione delegata gdown.access.
  5. Montate la configurazione qui sotto nell’immagine, in /opt/gdown/config/application.properties.

Cosa deve contenere il token

iss = https://login.microsoftonline.com/<tenant-id>/v2.0 (il vostro tenant, token v2); aud = il client id dell’API (un token per un’altra API è rifiutato); roles = i ruoli applicazione, associati a reader, writer o admin; tid = il vostro tenant (verificato tramite iss, o con allowed-tenants per più tenant); exp e la firma di Microsoft. Il claim scp è informativo: i diritti non ne dipendono.

Usate i ruoli applicazione invece del claim groups: oltre 200 gruppi Entra lo omette (overage), e gDown non chiama Microsoft Graph. Un token resta valido fino alla scadenza.

Licenza

Copyright (c) 2026 Gluonify. gDown è pubblicato sotto Business Source License 1.1: potete copiarlo, modificarlo, ridistribuirlo e usarlo in produzione, tranne che per fornire a terzi un servizio di database ospitato o gestito. Quattro anni dopo ogni versione, questa passa sotto licenza Apache 2.0. Per qualsiasi altro uso è disponibile una licenza commerciale. I componenti di terze parti restano sotto le proprie licenze, elencate nel file NOTICE del repository.

Neo4j, Bolt e Cypher sono marchi di Neo4j, Inc. openCypher è un progetto dell'openCypher Implementers Group (il suo TCK è sotto licenza Apache 2.0). Oracle, Java e GraalVM sono marchi di Oracle e/o delle sue affiliate. Red Hat, UBI e Mandrel sono marchi di Red Hat, Inc. Docker è un marchio di Docker, Inc. gDown e Gluonify non sono affiliati, sponsorizzati né approvati da nessuno di essi; «compatibile con» indica soltanto la compatibilità di protocollo e di linguaggio.