Neo4j deployment automation on AWS

Prerequisites

You have installed the AWS command-line interface.
You have generated an access token.
You have defined the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
You have installed jq tool for working with JSON responses. See the Download jq page.

CloudFormation

Neo4j provides CloudFormation templates for Neo4j Enterprise standalone, Neo4j Causal Cluster (highly-available clusters), and Neo4j Community.

CloudFormation is a recipe that tells AWS how to deploy a whole set of interrelated resources.

The Neo4j CloudFormation templates have the following properties:

Deploying one or more EC2 VMs in a specified region.
Deploying EC2 VMs in multiple availability zones within a region, so that if one goes down, your entire database does not go down.
Deploying a new virtual private cloud (VPC) and installing Neo4j in it. In this way, you can control network access by tuning your VPC and security rules.

Creating a CloudFormation stack

Depending on what Neo4j edition you want to deploy, you create a CloudFormation stack by running a bash script. Each script contains the following configurations:

The URL of the Neo4j stack template that tells AWS what to deploy.
Various parameters that control how much hardware you want to use.
SSHKEY – the name of your SSH key on AWS to be used to SSH into the instances as the user “ubuntu”.
NetworkWhitelist - it is set to 0.0.0.0/0 by default, which means that any IP on the internet can contact your instance. If you want to lock it down to just your company’s IP block, this is where you must specify that.
INSTANCE - the AWS instance type you want to launch, which controls your database capacity.
REGION - specifies where to deploy Neo4j. Possible values are: us-east-1, us-east-2, us-west-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-northeast-1, ap-south-1, and sa-east-1.

Deploying Neo4j Enterprise Standalone

To deploy Neo4j Enterprise Standalone, use the Single instance template. It does not have high-availability failover capabilities, but it is a very fast way to get started.

#!/bin/bash
VERSION=4.1.12
export SINGLE_TEMPLATE=http://neo4j-cloudformation.s3.amazonaws.com/neo4j-enterprise-standalone-stack-$VERSION.json
export STACKNAME=neo4j-enterprise-$(echo $VERSION | sed s/[^A-Za-z0-9]/-/g)
export INSTANCE=r4.large
export REGION=us-east-1
export SSHKEY=my-ssh-keyname
aws cloudformation create-stack \
   --stack-name $STACKNAME \
   --region $REGION \
   --template-url $SINGLE_TEMPLATE \
   --parameters ParameterKey=InstanceType,ParameterValue=$INSTANCE \
     ParameterKey=NetworkWhitelist,ParameterValue=0.0.0.0/0 \
     ParameterKey=Password,ParameterValue=s00pers3cret \
     ParameterKey=SSHKeyName,ParameterValue=$SSHKEY \
     ParameterKey=VolumeSizeGB,ParameterValue=37 \
     ParameterKey=VolumeType,ParameterValue=gp2 \
     --capabilities CAPABILITY_NAMED_IAM

Deploying Neo4j Enterprise Causal Cluster

To deploy Neo4j Enterprise Causal Cluster, use the Causal Cluster template.

You indicate how many core servers you want in your cluster by configuring the ClusterNodes parameter. Minimum value: 3.

#!/bin/bash
VERSION=4.1.12
export CLUSTER_TEMPLATE=http://neo4j-cloudformation.s3.amazonaws.com/neo4j-enterprise-stack-$VERSION.json
export STACKNAME=neo4j-enterprise-$(echo $VERSION | sed s/[^A-Za-z0-9]/-/g)
export INSTANCE=r4.large
export REGION=us-east-1
export SSHKEY=my-ssh-keyname
aws cloudformation create-stack \
   --stack-name $STACKNAME \
   --region $REGION \
   --template-url $CLUSTER_TEMPLATE \
   --parameters ParameterKey=ClusterNodes,ParameterValue=3 \
     ParameterKey=InstanceType,ParameterValue=$INSTANCE \
     ParameterKey=NetworkWhitelist,ParameterValue=0.0.0.0/0 \
     ParameterKey=Password,ParameterValue=s00pers3cret \
     ParameterKey=SSHKeyName,ParameterValue=$SSHKEY \
     ParameterKey=VolumeSizeGB,ParameterValue=37 \
     ParameterKey=VolumeType,ParameterValue=gp2 \
     --capabilities CAPABILITY_NAMED_IAM

Deploying Neo4j Community Standalone

To deploy Neo4j Community Standalone, use the Community template.

#!/bin/bash
VERSION=4.1.12
export COMMUNITY_TEMPLATE=http://neo4j-cloudformation.s3.amazonaws.com/neo4j-community-standalone-stack-$VERSION.json
export STACKNAME=neo4j-comm-$(echo $VERSION | sed s/[^A-Za-z0-9]/-/g)
export INSTANCE=r4.large
export REGION=us-east-1
export SSHKEY=my-ssh-keyname
aws cloudformation create-stack \
   --stack-name $STACKNAME \
   --region $REGION \
   --template-url $COMMUNITY_TEMPLATE \
   --parameters ParameterKey=InstanceType,ParameterValue=$INSTANCE \
     ParameterKey=NetworkWhitelist,ParameterValue=0.0.0.0/0 \
     ParameterKey=Password,ParameterValue=s00pers3cret \
     ParameterKey=SSHKeyName,ParameterValue=$SSHKEY \
     ParameterKey=VolumeSizeGB,ParameterValue=37 \
     ParameterKey=VolumeType,ParameterValue=gp2 \
     --capabilities CAPABILITY_NAMED_IAM

Checking to see if your instance is up

In each case, the commands submit a CloudFormation stack to be deployed, but they do not wait for the stack to be available. If you want to wait for the CloudFormation stack to finish deploying, use the following command:

aws cloudformation wait stack-create-complete --region $REGION --stack-name "$STACKNAME"

Finally, you can get the stack outputs, like this:

aws cloudformation describe-stacks --region $REGION --stack-name "$STACKNAME"

In general, this outputs a lot JSON content. To cut straight to the outputs of the stack, use the jq tool.

jq -r '.Stacks[0].Outputs[]'

The result is a set of outputs with the IP address and password of your new instance. By the time the CloudFormation template finishes deploying, the service will be live and ready to go.

Cleaning up and removing your stack

When you are done with your CloudFormation stack, you can delete it by using the following script:

#!/bin/bash
echo "Deleting stack $1"
aws cloudformation delete-stack --stack-name "$1" --region us-east-1