Neo4j es una base de datos de grafos: guarda la información como nodos y relaciones, lo que hace muy rápidas las consultas que recorren conexiones, como recomendaciones, detección de fraude, redes sociales o dependencias entre servicios. Se consulta con Cypher, un lenguaje declarativo basado en patrones. En este tutorial instalarás Neo4j Community Edition en Ubuntu 24.04 desde el repositorio oficial, ajustarás su memoria, crearás un pequeño grafo con Cypher, activarás la biblioteca APOC y harás una copia de seguridad con neo4j-admin.
Requisitos previos
Para seguir esta guía necesitas:
- Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath.
- Un usuario no root con privilegios
sudo. - Al menos 2 GB de RAM (4 GB o más si el grafo va a crecer).
- Un cliente SSH en tu equipo para acceder a Neo4j Browser mediante un túnel.
Paso 1: Instalar Java 21
Las versiones actuales de Neo4j (serie 2025 y posteriores, con numeración por calendario) necesitan Java 21. Instálalo desde los repositorios de Ubuntu:
sudo apt update
sudo apt install -y openjdk-21-jre-headless
Comprueba la versión:
java -version
openjdk version "21.0.8" 2025-07-15
OpenJDK Runtime Environment (build 21.0.8+9-Ubuntu-0ubuntu124.04.1)
OpenJDK 64-Bit Server VM (build 21.0.8+9-Ubuntu-0ubuntu124.04.1, mixed mode, sharing)
Paso 2: Añadir el repositorio de Neo4j e instalarlo
Descarga la clave de firma de Neo4j en /etc/apt/keyrings y añade el repositorio estable:
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/neotechnology.gpg
echo "deb [signed-by=/etc/apt/keyrings/neotechnology.gpg] https://debian.neo4j.com stable latest" | sudo tee /etc/apt/sources.list.d/neo4j.list
Instala Neo4j Community Edition, que incluye también cypher-shell:
sudo apt update
sudo apt install -y neo4j
Durante la instalación puede aparecer una pantalla con la licencia; acéptala para continuar. Comprueba la versión instalada:
neo4j --version
2025.08.0
Paso 3: Definir la contraseña inicial
Neo4j crea un usuario neo4j. Establece su contraseña antes del primer arranque, así no queda la contraseña por defecto en ningún momento. Sustituye your_strong_password (mínimo 8 caracteres):
sudo -u neo4j neo4j-admin dbms set-initial-password 'your_strong_password'
Changed password for user 'neo4j'. IMPORTANT: this change will only take effect if performed before the database is started for the first time.
Paso 4: Ajustar la memoria
Neo4j usa dos zonas de memoria: el heap de Java, para ejecutar consultas, y la page cache, donde mantiene en RAM los archivos del grafo. Si no las fijas, las calcula al arrancar y pueden variar. Pide a neo4j-admin una recomendación para la RAM de tu servidor:
sudo -u neo4j neo4j-admin server memory-recommendation
La salida termina con líneas como estas (el ejemplo es para un servidor de 4 GB):
server.memory.heap.initial_size=1g
server.memory.heap.max_size=1g
server.memory.pagecache.size=1g
Abre la configuración principal:
sudo nano /etc/neo4j/neo4j.conf
Busca esas tres claves (vienen comentadas con #), descoméntalas y pon los valores recomendados:
server.memory.heap.initial_size=1g
server.memory.heap.max_size=1g
server.memory.pagecache.size=1g
Deja server.default_listen_address comentado. Así Neo4j solo escucha en localhost y no queda expuesto a Internet; accederás a él con un túnel SSH.
Paso 5: Arrancar Neo4j
Habilita y arranca el servicio:
sudo systemctl enable --now neo4j
Comprueba el estado y espera a ver en el log que está listo:
sudo journalctl -u neo4j -n 20 --no-pager
... INFO Bolt enabled on localhost:7687.
... INFO HTTP enabled on localhost:7474.
... INFO Remote interface available at http://localhost:7474/
... INFO Started.
Neo4j escucha en dos puertos: 7687 para Bolt, el protocolo binario que usan los drivers y cypher-shell, y 7474 para HTTP y Neo4j Browser.
Conéctate con cypher-shell:
cypher-shell -u neo4j
Introduce la contraseña del paso 3 y lanza una consulta de prueba:
SHOW DATABASES YIELD name, currentStatus;
+-----------------------------+
| name | currentStatus |
+-----------------------------+
| "neo4j" | "online" |
| "system" | "online" |
+-----------------------------+
La edición Community tiene una única base de datos de usuario, neo4j, además de system, que guarda usuarios y configuración. Crear bases de datos adicionales requiere la edición Enterprise.
Paso 6: Crear restricciones e índices
Antes de cargar datos, define qué propiedades identifican cada tipo de nodo. Una restricción de unicidad impide duplicados y crea un índice automáticamente, lo que acelera las búsquedas por esa propiedad. En cypher-shell:
CREATE CONSTRAINT person_email IF NOT EXISTS
FOR (p:Person) REQUIRE p.email IS UNIQUE;
CREATE CONSTRAINT company_name IF NOT EXISTS
FOR (c:Company) REQUIRE c.name IS UNIQUE;
CREATE INDEX person_name IF NOT EXISTS
FOR (p:Person) ON (p.name);
Comprueba que se han creado:
SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state;
Los tres deben aparecer con state igual a "ONLINE".
Paso 7: Crear y consultar un grafo con Cypher
En Cypher, los nodos se escriben entre paréntesis y las relaciones entre corchetes con una flecha: (a:Person)-[:WORKS_AT]->(c:Company). MERGE crea el patrón solo si no existe, así que puedes repetir la carga sin duplicar datos:
MERGE (ana:Person {email: '[email protected]'}) SET ana.name = 'Ana'
MERGE (luis:Person {email: '[email protected]'}) SET luis.name = 'Luis'
MERGE (marta:Person {email: '[email protected]'}) SET marta.name = 'Marta'
MERGE (pablo:Person {email: '[email protected]'}) SET pablo.name = 'Pablo'
MERGE (acme:Company {name: 'Acme'})
MERGE (globex:Company {name: 'Globex'})
MERGE (ana)-[:WORKS_AT {since: 2021}]->(acme)
MERGE (luis)-[:WORKS_AT {since: 2023}]->(acme)
MERGE (marta)-[:WORKS_AT {since: 2020}]->(globex)
MERGE (ana)-[:KNOWS]->(marta)
MERGE (marta)-[:KNOWS]->(pablo);
0 rows
ready to start consuming query after 45 ms, results consumed after another 0 ms
Added 6 nodes, Set 13 properties, Created 5 relationships, Added 6 labels
Consulta quién trabaja en Acme:
MATCH (p:Person)-[r:WORKS_AT]->(c:Company {name: 'Acme'})
RETURN p.name AS persona, r.since AS desde
ORDER BY desde;
+----------------+
| persona | desde |
+----------------+
| "Ana" | 2021 |
| "Luis" | 2023 |
+----------------+
La ventaja de un grafo aparece al recorrer varios saltos. Esta consulta busca personas a las que Ana podría conocer a través de sus contactos (amigos de amigos a los que aún no conoce):
MATCH (ana:Person {name: 'Ana'})-[:KNOWS]->(:Person)-[:KNOWS]->(sugerencia:Person)
WHERE NOT (ana)-[:KNOWS]->(sugerencia) AND sugerencia <> ana
RETURN DISTINCT sugerencia.name AS sugerencia;
+------------+
| sugerencia |
+------------+
| "Pablo" |
+------------+
Y el camino más corto entre dos personas por cualquier tipo de relación:
MATCH path = shortestPath((a:Person {name: 'Luis'})-[*..6]-(b:Person {name: 'Pablo'}))
RETURN [n IN nodes(path) | coalesce(n.name, n.email)] AS camino;
+-----------------------------------------+
| camino |
+-----------------------------------------+
| ["Luis", "Acme", "Ana", "Marta", "Pablo"] |
+-----------------------------------------+
Antepón PROFILE a cualquier consulta para ver su plan de ejecución y comprobar que usa los índices (operadores NodeIndexSeek o NodeUniqueIndexSeek en lugar de NodeByLabelScan). Sal de cypher-shell con :exit.
Paso 8: Acceder a Neo4j Browser por túnel SSH
Neo4j Browser es la interfaz web para escribir consultas y ver el grafo dibujado. Como Neo4j solo escucha en localhost, abre un túnel SSH desde tu equipo que reenvíe ambos puertos. Sustituye your_user y your_server_ip:
ssh -L 7474:localhost:7474 -L 7687:localhost:7687 your_user@your_server_ip
Con la sesión abierta, entra en http://localhost:7474 en tu navegador, elige la URL de conexión neo4j://localhost:7687 e inicia sesión con neo4j y tu contraseña. Ejecuta MATCH (n) RETURN n para ver el grafo que has creado.
Advertenciasi necesitas que una aplicación en otro servidor se conecte a Bolt, descomenta
server.default_listen_address=0.0.0.0enneo4j.conf, configura TLS para Bolt y abre el puerto 7687 solo para la IP de la aplicación consudo ufw allow from your_app_ip to any port 7687 proto tcp.
Paso 9: Activar APOC Core
APOC es la biblioteca de procedimientos más utilizada de Neo4j: importación de JSON y CSV, utilidades de texto y fechas, refactorización del grafo y más. El paquete incluye APOC Core en el directorio labs; para activarlo, cópialo a plugins:
ls /var/lib/neo4j/labs/
sudo cp /var/lib/neo4j/labs/apoc-*-core.jar /var/lib/neo4j/plugins/
sudo chown neo4j:neo4j /var/lib/neo4j/plugins/apoc-*-core.jar
sudo systemctl restart neo4j
Verifica que se ha cargado:
cypher-shell -u neo4j "RETURN apoc.version() AS apoc;"
+-------------+
| apoc |
+-------------+
| "2025.08.0" |
+-------------+
La versión de APOC coincide con la de Neo4j. Tras cada actualización de Neo4j, repite la copia para usar el JAR de la nueva versión y borra el anterior de plugins.
Paso 10: Hacer y restaurar copias de seguridad
En la edición Community, las copias se hacen con la base de datos detenida mediante neo4j-admin database dump, que genera un único archivo .dump. Crea el directorio de destino:
sudo mkdir -p /var/backups/neo4j
sudo chown neo4j:neo4j /var/backups/neo4j
Detén Neo4j, genera el volcado y vuelve a arrancarlo:
sudo systemctl stop neo4j
sudo -u neo4j neo4j-admin database dump neo4j --to-path=/var/backups/neo4j
sudo systemctl start neo4j
Comprueba que el archivo existe:
ls -lh /var/backups/neo4j
-rw-r--r-- 1 neo4j neo4j 13K Sep 25 11:02 neo4j.dump
Para restaurar, detén Neo4j y carga el volcado sobre la base de datos existente:
sudo systemctl stop neo4j
sudo -u neo4j neo4j-admin database load neo4j --from-path=/var/backups/neo4j --overwrite-destination=true
sudo systemctl start neo4j
Copia los archivos .dump fuera del servidor para que la copia sobreviva a un fallo del disco.
Solución de problemas
- El servicio no arranca: revisa
sudo journalctl -u neo4j -n 50y/var/log/neo4j/. Lo más habitual es una versión de Java incorrecta (compruebajava -version) o un valor de memoria mayor que la RAM disponible enneo4j.conf. The client is unauthorized due to authentication failure: la contraseña no coincide. Si fijaste la contraseña después del primer arranque, no se aplicó; cámbiala desdecypher-shellconALTER CURRENT USER SET PASSWORD FROM 'actual' TO 'nueva';.Unknown function 'apoc.version': el JAR no está en/var/lib/neo4j/plugins/, no pertenece al usuarioneo4jo no has reiniciado el servicio.- Neo4j Browser no conecta con Bolt: el túnel debe reenviar también el puerto 7687, no solo el 7474.
Conclusión
Has instalado Neo4j Community Edition en Ubuntu 24.04, has ajustado su memoria, has creado un grafo con restricciones, índices y consultas de varios saltos en Cypher, has activado APOC y has hecho una copia de seguridad restaurable.
Como siguientes pasos, puedes:
- Importar datos masivos desde CSV con
LOAD CSVo conneo4j-admin database importpara cargas iniciales grandes. - Conectar tu aplicación con el driver oficial de Neo4j para Python, JavaScript, Java o Go.
- Automatizar los volcados con un temporizador de systemd y enviarlos a almacenamiento externo.