Introduction

Neo4j is a highly scalable, native graph database designed to handle complex data relationships efficiently. It is widely used for applications such as social networks, recommendation engines, fraud detection, and more.

In this guide, we will walk you through the process of installing and using Neo4j on Debian 12 using Docker and Ansible. By the end of this article, you will have a fully functional Neo4j instance running in a Dockerized environment, managed by Ansible.

Prerequisites

Before we begin, ensure that you have the following prerequisites:

• Debian 12: A server running Debian 12 with root or sudo access.
• Docker: Docker installed on your Debian 12 server. You can follow the official Docker installation guide.
• Docker Compose: Docker Compose installed. Follow the official Docker Compose installation guide.
• Ansible: Ansible installed on your local machine or control node. Follow the official Ansible installation guide.
• Basic Knowledge: Familiarity with Docker, Ansible, and Linux command-line operations.

Step 1: Set Up Docker and Docker Compose

First, ensure that Docker and Docker Compose are installed and running on your Debian 12 server.

Install Docker

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

Install Docker Compose

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Step 2: Create a Docker Compose File for Neo4j

Create a directory for your Neo4j setup and navigate into it:

mkdir neo4j-setup
cd neo4j-setup

Create a docker-compose.yml file:

version: '3.8'

services:
  neo4j:
    image: neo4j:latest
    container_name: neo4j
    restart: always
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      - NEO4J_AUTH=neo4j/yourpassword
    volumes:
      - neo4j_data:/data
    networks:
      - neo4j_network

volumes:
  neo4j_data:

networks:
  neo4j_network:

This Docker Compose file defines a Neo4j service. It exposes ports 7474 (HTTP API and UI) and 7687 (Bolt protocol). Replace yourpassword with a secure password for the Neo4j instance.

Step 3: Deploy with Docker Compose

Run the following command to start the Neo4j container:

docker-compose up -d

This command will pull the Neo4j Docker image and start the container in detached mode.

Step 4: Automate with Ansible

To automate the deployment process, create an Ansible playbook named deploy_neo4j.yml:

---
- hosts: all
  become: yes
  tasks:
    - name: Ensure Docker is installed
      apt:
        name: docker-ce
        state: present

    - name: Ensure Docker Compose is installed
      get_url:
        url: https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)
        dest: /usr/local/bin/docker-compose
        mode: '0755'

    - name: Start and enable Docker service
      service:
        name: docker
        state: started
        enabled: yes

    - name: Create Neo4j setup directory
      file:
        path: /opt/neo4j-setup
        state: directory

    - name: Copy Docker Compose file
      copy:
        src: docker-compose.yml
        dest: /opt/neo4j-setup/docker-compose.yml

    - name: Deploy Neo4j with Docker Compose
      command: docker-compose up -d
      args:
        chdir: /opt/neo4j-setup

Run the playbook using the following command:

ansible-playbook -i your_inventory_file deploy_neo4j.yml

Replace your_inventory_file with the path to your Ansible inventory file.

Step 5: Access Neo4j Browser

Once the deployment is complete, open your web browser and navigate to http://your_server_ip:7474. You should see the Neo4j Browser interface. Log in using the username neo4j and the password you set in the Docker Compose file.

Step 6: Verify Neo4j

To verify that the Neo4j instance is running correctly, you can use the Neo4j Browser or the Cypher shell.

Using Neo4j Browser

Run a simple Cypher query in the Neo4j Browser to verify connectivity:

MATCH (n) RETURN n LIMIT 25;

This query returns up to 25 nodes from the database.

Using Cypher Shell

Access the Neo4j container and run the Cypher shell:

docker exec -it neo4j cypher-shell -u neo4j -p yourpassword

Run the same query to verify connectivity:

MATCH (n) RETURN n LIMIT 25;

Step 7: Use Neo4j

Now that Neo4j is up and running, you can start using it for your graph database needs. Here are some common tasks:

Create Nodes and Relationships

Use Cypher queries to create nodes and relationships:

CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'});

Query Data

Retrieve data using Cypher queries:

MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a, b;

Import Data

You can import data from CSV files or other sources using the LOAD CSV command or Neo4j’s import tools.

Conclusion

In this guide, we walked you through the process of installing and using Neo4j Graph Database on Debian 12 using Docker and Ansible. By following these steps, you can easily set up a Neo4j instance for managing complex data relationships.

Docker and Ansible make it easy to manage and automate your deployments, ensuring a smooth and consistent setup process. Whether you’re running a small project or a large-scale application, this setup provides a robust foundation for your graph database needs.