Neo4J with Basic Authentication on Digital Ocean

In this post I’m going to take you through the steps of setting up a Neo4J instance on Digital Ocean and how to secure it with either the Authentication Extension if you are using a version of Neo4J 2.1.x and below or the out of the box functionality in 2.2.x. and above.

It is written from the point of view of being a sandbox environment on the web, and that your limitations are mainly cost motivated. If ease and cost are less of a factor, take a look at GrapheneDB; which will have you up and running in next to no time. Their free hobby tier however is extremely stingy with a 1000 node limit, hence why I am bringing you this.

In the past I have discussed setting up a reverse proxy with Apache to do something similar, however published back in 2013 I wanted to bring an update. In this case using a Neo4J extension rather than running another process like Apache or Nginx.

1) Sign up.

If you sign up with this link you can receive a $10 credit . In the interest of full disclosure, if you become a paying customer I also receive and account credit also ;-).

2) Create a Droplet

So we’re going to actually create small instance, which at the time of writing 512MB RAM for $5 a month. This may sound small (and indeed is), but we are going to configure some Swap memory to help mitigate any memory concerns.

As I said I am assuming this is more of a personal playground than a production system. In any case Digital Ocean allows you to resize your Droplet, so if you need more in the future, the option is open to you.

When creating a droplet bare in mind the location, if your going to be putting a front end on the application it should be geographically close to the server holding that. Otherwise the chatty-ness of a ReST interface can be debilitatingly slow.

3) Configure Swap

Now we have our instance the first we need to do is increase the amount of memory we have available to us. We’re going to create a big lump of swap memory to use on our as standard SSD provided by Digital Ocean.

Log into your server and execute the following:

free -m

You should see your have you Mem: usage in MB and a total of around ~500. The Swap: as zero.

df -h

This will give us our disk usage. Assuming you haven’t done anything with the your box you should have the best part of ~20Gb to put to use.

sudo fallocate -l 1500M /swapfile

This creates the physical file that will be used for swap memory. We’re going to create about ~1.5GB, which is a little above the rule of thumb; however take us to the recommended 2GB for running a Neo4J Server. Although the “recommended” minimum amount by the Neo4J team this is in a production setting. For a toy database this is plenty.

df -h

You should now see the space gobbled up in your disk usage.

sudo chmod 600 /swapfile

To permissions the swap file to only the owner, which should be root.

ls -lh /swapfile

To double check.

sudo mkswap /swapfile

Inform linux that the swapfile is a swap area

sudo swapon /swapfile

Enable the file for use as swap memory.

free -m

You should now see that the memory information displayed now includes Swap (even though it is probably unused as yet)

The next thing to do is make a entry in the fstab file so the operating system knows to use the file in the event of a reboot.

sudo nano /etc/fstab

This opens a file editor in which you should see tab delimitted headers and one existing entry, starting with a UUID. Under that line add:

/swapfile none swap sw 0 0

Being careful with the tabs & whitespace.

Ctrl+O

Saves

Ctrl+X

To Exit

So now we have created the swap memory and ensured it is used on startup. Now we’re going to tweak some of the arguments to determine the “swappiness” and “caching pressure”. Think of these as being how we prefer the operating system to use the swap memory in conjunction with it’s actual memory.

sudo sysctl vm.swappiness=10

sudo sysctl vm.vfs_cache_pressure=50

Set the swappiness and cache pressure, these are fairly standard parameters for a linux configuration not being used as a UI.

cat /proc/sys/vm/swappiness

cat /proc/sys/vm/vfs_cache_pressure

Check that the properties are set correctly. They should return the values set in the previous step.

poweroff

This will shutdown your server. We’re not doing this as it is required to make swap work; rather I recommend verifying what you have done so far.

You will need to restart server from the dashboard on DigitalOcean.com. Once it’s status is back to ‘Active’ you can login using ssh again.

Use the free and the cat commands from above to check that swap is being used with the parameters we set out.

4) Install Neo4J

So in order to install Neo4J we’re going to have to update the list of packages on our box. Executing the following will install the latest stable version of the Community edition. If you would like alternative version or prefer life on the bleeding edge refer to this link.

wget -O - http://debian.neo4j.org/neotechnology.gpg.key| apt-key add - 

echo 'deb http://debian.neo4j.org/repo stable/' > /etc/apt/sources.list.d/neo4j.list

aptitude update -y # Find out about the files in our repository 

aptitude install neo4j -y # Install Neo4j, community edition  

Once installed the Neo4J server should start automatically.

A few useful ways to check are:

service neo4j-service status

Should tell you neo4j is running

ps -ef | grep neo4j

This should show you Java process with several neo4j jars on a the classpath.

curl http://localhost:7474

This should return a small json fragment, with some endpoint information, which you are hopefully familiar with.

At the moment our server only accepts incomming requests from the same machine it is hosted on, which is the default ‘safety first’ approach. So lets open the neo4j-server.properties file:

nano /var/lib/neo4j/conf/neo4j-server.properties

Then uncomment the following line (remove the hash):

#org.neo4j.server.webserver.address=0.0.0.0

Ctrl+O and Ctrl+X to save and exit.

This will allow you to access the Neo4J ReST endpoints and subsequently the Browser UI from anywhere. We’ll verify that momentarily, but your next steps will vary with what version of Neo4J server you are running.

Configure Access (Neo4J 2.2.x and above)

The most recent versions of Neo4J have provided basic authentication out of the box, and setup is a doddle. If you’re obliged to use and older version of Neo4J see the Authentication Plugin section below.

The first time you access the console through a browser http://<your.server.ip>:7474, you will be prompted to login with the default user neo4j and password neo4j then create a password of your choosing. You’re done!

Authentication Plugin (Neo4J 2.1.x and below)

Now let’s stop the service and install the authentication plugin.

service neo4j-service stop

Head to the extension page and download the latest precompiled jar (at the bottom of the README).

Using an FTP client, drop this jar file into:

/var/lib/neo4j/plugins

Open the neo4j-server.properties file again:

nano /var/lib/neo4j/conf/neo4j-server.properties

Add the following lines (bottom is fine) using suitable replacements for username and password.

org.neo4j.server.credentials=username:password

org.neo4j.server.thirdparty_jaxrs_classes=org.neo4j.server.extension.auth=/auth  

Ctrl+O and Ctrl+X to save and exit.

Start Service

service neo4j-service start

If you have done everything correctly you should now be able to navigate to http://<your.server.ip>:7474 where you will should a basic auth dialog, which will take the values you entered in the neo4j-server.properties file.

To add more user accounts refer to the README on the plugin extension page.

Check Authentication

So whether or not you’re using the latest version of Neo4J and the build in basic authentication or the plugin extension the following will still apply.
If you try accessing the web console through your browser you should be prompted for a user name and password. We can also check the ReST endpoints as well though. As the Neo4
From your servers command prompt use curl to try and access the base url:
curl http://localhost:7474/db/data/ You should get a No authorization header supplied message. This is good it means you configuration has worked.
Now try (changing the password appropriately):
curl --user neo4j:password http://localhost:7474/db/data/ You should now see a list of base endpoints that can be interrogated for your database.

Final Thought

So there we go. You now have you own Neo4J sandbox available in the wild. At $5 a month you have a cheaper and significantly bigger instance available to you than on GrapheneDB!

Neo4J with Basic Authentication on Digital Ocean