Docker first look guide

Docker compose can be used to provision a set of related containers as services to experiment with or to run in test environments.

Docker does not recommend using compose for production.

The manual installation, configuring and running of agents on the Neo4j containers is lost if the container is stopped.

Prerequisites

  • unix-based operating system

  • Docker

  • Docker compose

Prepare hosts file

You need to set up the following host names in your /etc/hosts or C:/windows/system32/drivers/etc/hosts file;

127.0.0.1   storage server db-single

Create persistence DBMS and NOM server

Create an empty directory for self-signed certificates

Create a directory ~/.nom/ssc on your local machine before running Docker compose. The compose file below specifies that:

  • This directory will be mounted into the docker container.

  • Self-signed certificates will be generated and saved to the mounted directory during the container start up.

  • The generated certificates are used by the NOM server

These certificates are used by the server itself but are also required to configure the NOM agent.

For sudo docker compose command, make sure the correct path to .nom/ssc is set in the bind section below.

Copy docker compose file

Following is a docker compose file that can be used to start up a NOM server and Enerprise Neo4j Persistence system without any customization. Copy this to your local machine as docker-compose.yaml.

Edit the yaml as follows:

  • replace all three occurences of <PERSISTENCE_PASSWORD> with a secure password.

  • replace all three occurences of <SSC_PASSWORD> with a secure password.

docker-compose.yaml
networks:
  lan:

services:
  storage:
    hostname: storage
    image: neo4j:4.4.8-enterprise
    networks:
      - lan
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      NEO4J_ACCEPT_LICENSE_AGREEMENT: "yes"
      NEO4J_AUTH: neo4j/<PERSISTENCE_PASSWORD>
      NEO4J_dbms_default__advertised__address: storage
      NEO4J_dbms_connector_http_listen__address: storage:9000
      NEO4J_dbms_connector_bolt_listen__address: storage:9001
    healthcheck:
      test: [ "CMD-SHELL", "echo RETURN 1 | cypher-shell -a bolt://storage:9001 -u neo4j -p <PERSISTENCE_PASSWORD> || exit 1" ]

  server:
    hostname: server
    image: neo4j/neo4j-ops-manager-server
    depends_on:
      storage:
        condition: service_healthy
    networks:
      - lan
    ports:
      - "8080:8080"
      - "9090:9090"
    environment:
      SPRING_NEO4J_URI: bolt://storage:9001
      SPRING_NEO4J_AUTHENTICATION_USERNAME: neo4j
      SPRING_NEO4J_AUTHENTICATION_PASSWORD: <PERSISTENCE_PASSWORD>
      SERVER_SSL_KEY_STORE_TYPE: PKCS12
      SERVER_SSL_KEY_STORE: file:/certificates/server.pfx
      SERVER_SSL_KEY_STORE_PASSWORD: <SSC_PASSWORD>
      GRPC_SERVER_SECURITY_KEY_STORE_TYPE: PKCS12
      GRPC_SERVER_SECURITY_KEY_STORE: file:/certificates/server.pfx
      GRPC_SERVER_SECURITY_KEY_STORE_PASSWORD: <SSC_PASSWORD>
      CORS_ALLOWEDHEADERS: "*"
      CORS_ALLOWEDORIGINS: "http://localhost:[*],https://localhost:[*], http://server:[*]"
    volumes:
      - type: bind
        source: ~/.nom/ssc
        target: /certificates
    entrypoint:
      - "sh"
      - "-c"
      - "java -jar app.jar ssc -n server -o /certificates -p <SSC_PASSWORD> -d server -i 127.0.0.1 && java -jar app.jar"

Documentation for NOM server docker image is here.

Run docker compose

Run the follwing command:

docker compose -f docker-compose.yaml up <folder for context, typically current folder>

Open NOM UI

Wait for the server container to start and then go to https://server:8080. Login as admin:passw0rd and accept license terms.

Set up instance and agent

Register agent

In NOM UI - navigate to Agent settings (clicking on the sad robot takes you to the correct page) and add a new agent. Copy environment variables that are provided.

Full documentation on registering an agent is here.

Create docker compose file for Neo4j instance (pre-configured for agent)

Copy compose file below into docker-compose.instance.yaml and edit as follows:

  • Replace <CONFIG_TOKEN_CLIENT_ID from register agent step> and <CONFIG_TOKEN_CLIENT_SECRET from register agent step> with the values shown during the reigister agent step in the NOM UI.

  • Replace all three occurences of <NEO4J_INSTANCE_PASSWORD> with a secure password.

docker-compose.instance.yaml
services:
  db-single:
    hostname: db-single
    image: neo4j:5.5.0-enterprise
    networks:
      - lan
    ports:
      - "10000:10000"
      - "10001:10001"
    environment:
      CONFIG_SERVER_ADDRESS: "server:9090"
      CONFIG_TOKEN_URL: "https://server:8080/api/login/agent"
      CONFIG_TOKEN_CLIENT_ID: "<CONFIG_TOKEN_CLIENT_ID from register agent step>"
      CONFIG_TOKEN_CLIENT_SECRET: "<CONFIG_TOKEN_CLIENT_SECRET from register agent step>"
      CONFIG_TLS_TRUSTED_CERTS: "/certificates/server.cer"
      CONFIG_LOG_LEVEL: "debug"
      CONFIG_INSTANCE_1_NAME: "single-instance"
      CONFIG_INSTANCE_1_BOLT_URI: "bolt://db-single:10001"
      CONFIG_INSTANCE_1_BOLT_USERNAME: "neo4j"
      CONFIG_INSTANCE_1_BOLT_PASSWORD: <NEO4J_INSTANCE_PASSWORD>
      CONFIG_INSTANCE_1_QUERY_LOG_PORT: "9500"
      CONFIG_INSTANCE_1_LOG_CONFIG_PATH: "/var/lib/neo4j/conf/server-logs.xml"
      CONFIG_INSTANCE_1_QUERY_LOG_MIN_DURATION: "1"
      NEO4J_ACCEPT_LICENSE_AGREEMENT: "yes"
      NEO4J_AUTH: neo4j/<NEO4J_INSTANCE_PASSWORD>
      NEO4J_EDITION: "enterprise"
      NEO4J_server_default__advertised__address: db-single
      NEO4J_server_http_listen__address: db-single:10000
      NEO4J_server_bolt_listen__address: db-single:10001
      NEO4J_server_bolt_advertised__address: db-single:10001
      NEO4J_server_metrics_prometheus_enabled: "true"
      NEO4J_server_metrics_prometheus_endpoint: "localhost:2004"
      NEO4J_server_metrics_filter: "*"
    volumes:
       - type: bind
          source: ~/.nom/ssc
          target: /certificates
    healthcheck:
      test: [ "CMD-SHELL", "echo RETURN 1 | cypher-shell -a bolt://db-single:10001 -u neo4j -p <NEO4J_INSTANCE_PASSWORD> || exit 1" ]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 5s

Run docker compose

Run the follwing command:

docker compose -f docker-compose.instance.yaml up <folder for context, typically current folder>

Run agent

docker compose -f docker-compose.instance.yaml exec sh -c tar -xvf products/neo4j-ops-manager-agent-*-linux-amd64.tar.gz && neo4j-ops-manager-agent-*/bin/agent console

Explore NOM UI

Go to NOM UI and wait for DBMS to appear - this may take a few minutes. You should be able to see that the agent has connected in the agents listing. Once the DBMS is shown in the home page, double click on the name (initially a generated string) to edit it. Double click on the DBMS to see the metrics, status, security panel, logs and upgrade pages for the DBMS.