Quickstart: Deploy a Neo4j instance to a local Kubernetes installation via Docker Desktop for Mac

A quick start guide for deploying a Neo4j instance to a local Kubernetes installation (via Docker Desktop for Mac OS) using Neo4j Helm charts.

1. Prerequisites

2. Create a Helm deployment values file

Create a new file my-neo4j.values.yaml with the following content:

neo4j:
  resources:
    cpu: "1"
    memory: "2Gi"

  # Uncomment to set the initial password
  #password: "my-initial-password"

  # Uncomment to use enterprise edition
  #edition: "enterprise"
  #acceptLicenseAgreement: "yes"

volumes:
  data:
    mode: defaultStorageClass
    defaultStorageClass:
      requests:
        storage: 2Gi

For details of all Neo4j Helm chart configuration options, see Configure and install Neo4j using a customized Helm chart.

By default, the helm chart installs Neo4j Community Edition. If you want to install Neo4j Enterprise Edition, uncomment the configuration parameters edition: "enterprise" and acceptLicenseAgreement: "yes" in my-neo4j.values.yaml.

3. Create a Neo4j instance using dynamically provisioned storage

  1. Ensure your Helm Chart repositories are up to date:

    helm repo update
  2. Install Neo4j using the deployment values file created in Create a Helm deployment values file:

    helm install my-neo4j-release neo4j/neo4j-standalone -f my-neo4j.values.yaml
    NAME: my-neo4j-release
    LAST DEPLOYED: Thu Jun 10 10:43:01 2021
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    Thank you for installing neo4j.
    
    Your release "my-neo4j-release" has been installed .
    
    To view the progress of the rollout try:
    
      $ kubectl rollout status --watch --timeout=600s statefulset/my-neo4j-release
    
    Once rollout is complete you can log in to Neo4j at "neo4j://my-neo4j-release.default.svc.cluster.local:7687". Try:
    
      $ kubectl run --rm -it --image "neo4j:4.3.2" cypher-shell \
         -- cypher-shell -a "neo4j://my-neo4j-release.default.svc.cluster.local:7687" -u neo4j
    
    Graphs are everywhere!

    The command creates a Neo4j StatefulSet that relies on the default Kubernetes StorageClass to dynamically create a persistent volume. Generally speaking, when using Docker Desktop this volume will not survive a Kubernetes restart.

  3. Run the kubectl rollout command provided in the output of helm install to watch the Neo4j’s rollout until it is complete.

    kubectl rollout status --watch --timeout=600s statefulset/my-neo4j-release

    Since you have not passed a password for the neo4j user, the Neo4j Helm chart has set an automatically generated one. You can find it in the Helm install output. Please make a note of it.

4. Verify the installation

  1. Check that statefulset is OK. Initially it will not be ready but just check there is something there.

    kubectl get statefulsets
    NAME         READY   AGE
    <release-name>   1/1     5m11s
  2. Check that the PVC is OK (the STATUS must be Bound):

    kubectl get pvc
    NAME                STATUS   VOLUME          CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    data-<release-name>-0   Bound    <release-name>-pv   10Gi      RWO            manual         8m36s
  3. Check that the pod is READY:

    kubectl get pods
    NAME              READY    STATUS     RESTARTS   AGE
    <release-name>-0   1/1     Running      0          5m53s
  4. Check that the pod logs look OK:

    kubectl exec <pod-name> -- tail -n50 /logs/neo4j.log
    Changed password for user 'neo4j'.
    Directories in use:
      home:         /var/lib/neo4j
      config:       /config/
      logs:         /data/logs
      plugins:      /var/lib/neo4j/plugins
      import:       /var/lib/neo4j/import
      data:         /var/lib/neo4j/data
      certificates: /var/lib/neo4j/certificates
      run:          /var/lib/neo4j/run
    Starting Neo4j.
    2021-06-02 17:38:27.791+0000 INFO  Command expansion is explicitly enabled for configuration
    2021-06-02 17:38:27.819+0000 INFO  Starting...
    2021-06-02 17:38:31.195+0000 INFO  ======== Neo4j 4.3.2 ========
    2021-06-02 17:38:34.168+0000 INFO  Initializing system graph model for component 'security-users' with version -1 and status UNINITIALIZED
    2021-06-02 17:38:34.188+0000 INFO  Setting up initial user from `auth.ini` file: neo4j
    2021-06-02 17:38:34.190+0000 INFO  Creating new user 'neo4j' (passwordChangeRequired=false, suspended=false)
    2021-06-02 17:38:34.205+0000 INFO  Setting version for 'security-users' to 2
    2021-06-02 17:38:34.214+0000 INFO  After initialization of system graph model component 'security-users' have version 2 and status CURRENT
    2021-06-02 17:38:34.223+0000 INFO  Performing postInitialization step for component 'security-users' with version 2 and status CURRENT
    2021-06-02 17:38:34.561+0000 INFO  Bolt enabled on 0.0.0.0:7687.
    2021-06-02 17:38:36.910+0000 INFO  Remote interface available at http://localhost:7474/
    2021-06-02 17:38:36.912+0000 INFO  Started.
  5. Check that the services look OK:

    kubectl get services
    NAME                     TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                                        AGE
    kubernetes               ClusterIP      10.96.0.1        <none>        443/TCP                                        3d1h
    my-neo4j-release         ClusterIP      10.103.103.142   <none>        7687/TCP,7474/TCP,7473/TCP                     2d8h
    my-neo4j-release-admin   ClusterIP      10.99.11.122     <none>        6362/TCP,7687/TCP,7474/TCP,7473/TCP            2d8h
    my-neo4j-release-neo4j   LoadBalancer   10.110.138.165   localhost     7474:31237/TCP,7473:32026/TCP,7687:32169/TCP   2d3h
  6. Use port forwarding to get access to the browser:

    kubectl port-forward svc/<release-name> tcp-bolt tcp-http tcp-https
  7. In a web browser, open the Neo4j Browser at http://localhost:7474.

  8. Use the automatically generated password (as printed in the output of the helm install command) or the one you have set up with the helm install command.

5. Uninstall Neo4j and clean up your Docker Desktop

5.1. Uninstall Neo4j Helm deployment

  1. Uninstall Neo4j Helm deployment.

    helm uninstall <release-name>
    release "<release-name>" uninstalled
  2. Check the name of the PersistentVolumeClaim (pvc):

    kubectl get pvc
    NAME                STATUS   VOLUME          CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    data-<release-name>-0   Bound    <release-name>-pv   1Ti        RWO            manual         43h

    If you re-create Neo4j with the same settings, it will pick up the PVC again, and all the data is still on it.

    When you use dynamically provisioned volumes and delete the PersistentVolume, the underlying data may or may not be removed, depending on the Docker Desktop version and configuration.

5.2. Fully remove all the data and resources

To fully remove all the data and resources, delete the PersistentVolumeClaim in Kubernetes.

The dynamically provisioned volumes are automatically removed when the PersistentVolumeClaim is deleted.

kubectl delete pvc <pvc-name>
persistentvolumeclaim "data-<release-name>-0" deleted