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.
Prepare hosts file
You need to set up the following host names in your /etc/hosts
file:
127.0.0.1 storage server db-single
Generate self-signed certificates
-
Create a directory
~/.nom/ssc
on your local machine before running Docker compose. The compose files below specify that this directory will be mounted into the Docker container to make the generated certificates available to the NOM server and the agent. -
Change to
~/.nom/ssc
and generate self-signed certificates usingserver
as common name (CN) and DNS name, and127.0.0.1
as IP address (details see here):openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -subj "/CN=server" \ -addext "subjectAltName = DNS:server, IP:127.0.0.1" \ -addext "keyUsage = critical, digitalSignature, keyEncipherment" \ -addext "extendedKeyUsage = serverAuth" \ -addext "authorityKeyIdentifier = keyid:always,issuer:always" \ -keyout "server.key" \ -out "server.cer" openssl pkcs12 -export \ -inkey "server.key" \ -in "server.cer" \ -out "server.pfx" \ -password "pass:changeit"
This results in the creation of
server.cer
,server.key
andserver.pfx
. -
Use the password applied for the certificate store (
changeit
) instead of<SSC_PASSWORD>
in the next sections.
To keep this example simple, the generated certificates are used for both NOM server and agents. |
Create the Docker compose file
Following is a Docker compose file that can be used to start up a NOM server including its persistence and a single Neo4j Enterprise instance that will be managed by NOM.
Create the file docker-compose.yaml
in an empty directory on your local machine.
This directory is referenced as INSTALLATION_ROOT
later in this document.
networks:
lan:
services:
storage:
hostname: storage
image: neo4j:enterprise
networks:
- lan
ports:
- "9000:9000"
- "9001:9001"
environment:
NEO4J_ACCEPT_LICENSE_AGREEMENT: "yes"
NEO4J_AUTH: neo4j/<PERSISTENCE_PASSWORD>
NEO4J_server_default__advertised__address: storage
NEO4J_server_http_listen__address: storage:9000
NEO4J_server_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:[*]"
GRPC_SERVER_SECURITY_TRUST_CERT_COLLECTION: file:/certificates/server.cer
volumes:
- type: bind
source: ~/.nom/ssc
target: /certificates
entrypoint:
- "sh"
- "-c"
- "java -jar app.jar"
db-single:
hostname: db-single
image: neo4j:enterprise
networks:
- lan
ports:
- "10000:10000"
- "10001:10001"
environment:
CONFIG_SERVER_GRPC_ADDRESS: "server:9090"
CONFIG_SERVER_HTTP_ADDRESS: "https://server:8080"
CONFIG_TLS_TRUSTED_CERTS: "/certificates/server.cer"
CONFIG_TLS_CLIENT_CERT: "/certificates/server.cer"
CONFIG_TLS_CLIENT_KEY: "/certificates/server.key"
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
- type: bind
source: agent
target: /agent
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
Documentation for NOM server Docker image is here.
Edit docker-compose.yaml
as follows:
-
Replace all occurrences of
<SSC_PASSWORD>
with the certificate store password applied above. -
Replace all occurrences of
<PERSISTENCE_PASSWORD>
with a secure password. -
Replace all occurrences of
<NEO4J_INSTANCE_PASSWORD>
with a secure password.
Download the NOM agent
Download NOM agent binaries TAR from the Deployment Center and execute the following commands in your INSTALLATION_ROOT
:
mkdir agent
tar -xvf <DOWNLOADED_AGENT_BINARIES_TAR> -C agent --strip-components=1
Start the Docker compose environment
Run the following command in your INSTALLATION_ROOT
:
docker compose -f docker-compose.yaml up
Watch the output and make sure that the Docker containers storage
, server
and db-single
are started successfully.
Start the NOM agent
In INSTALLATION_ROOT
, start the agent in self-registration mode:
docker compose -f docker-compose.yaml exec db-single sh -c "/agent/bin/agent console -s"
Full documentation on registering an agent is here.
Explore NOM UI
-
Wait for the server container to start and then go to https://server:8080.
-
Login as
admin
/passw0rd
and accept license terms. -
Click the top right settings icon that redirects you to the global settings.
-
Make sure that the agent is online. Rename the agent if required.
-
Return to the main page and wait for DBMS to appear - this may take a few minutes. 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.
Controlling Docker containers
Stopping
-
To stop the complete NOM environment, press
Ctrl-C
on the Docker compose console and the agent console. -
To stop a single Docker container, issue
docker container stop <CONTAINER_NAME>
. To list containers usedocker ps
.
Since Docker keeps persisted data in container volumes, restarted containers will keep the previous state. |