neo4j

Runs the Neo4j graph database in Docker, with the Neo4j Browser on port 7474 and Bolt on port 7687.

Use it on boxctl

On the dashboard, pick neo4j in the Template picker and click Boot box.
The box boots, then runs neo4j/neo4j.sh on itself. The button reads Booting… until the script has finished.
Open the box's Terminal and follow the guide below. The box's row keeps a link back to this page under the template's name.

Once it is up, these are the commands to start from. The box's row lists them too.

Run on the box	What it does
`cat /opt/neo4j/password`	Show the password of the neo4j user.
`docker exec -it neo4j cypher-shell -u neo4j -p "$(cat /opt/neo4j/password)"`	Open a Cypher shell on the database.
`docker logs -f neo4j`	Follow the server log.

The guide is shared with the onctl CLI, so it starts from an onctl up -a neo4j/neo4j.sh command. Booting a box with this template replaces that command; everything the guide runs on the VM itself applies as written.

Options

boxctl cannot pass options to a template yet, so each of these keeps its default.

Option	Required	What it sets
`NEO4J_PASSWORD`	No	Password of the neo4j user, at least 8 characters (default: generated, printed at the end and kept in NEO4J_HOME/password).
`NEO4J_VERSION`	No	Image tag (default: 2026.09.0).
`NEO4J_HOME`	No	Directory on the VM for data, logs and the password file (default: /opt/neo4j).
`BOLT_ADVERTISED_ADDRESS`	No	host:port clients reach Bolt on, when it isn't the VM's own address on 7687, e.g. the public URL of port 7687 with :443.

Neo4j

Runs Neo4j Community in Docker, with its data kept on the VM in /opt/neo4j.

onctl up -n graph -a neo4j/neo4j.sh

The script installs Docker if the VM doesn't have it, starts the container, waits until Neo4j answers and prints the address, the user (neo4j) and the password. Without NEO4J_PASSWORD it generates one. Either way the password is kept in /opt/neo4j/password, readable by root only.

Give the VM 2 GB of memory or more.

Ports

Port	What
`7474`	HTTP: the Neo4j Browser (the dashboard), and the HTTP query API
`7687`	Bolt: what the Browser, drivers and `cypher-shell` talk to

The Browser needs both. Port 7474 only delivers the web app; the app then opens its own Bolt connection from your machine to port 7687 to log in and run queries. With only 7474 reachable the page loads and the login fails.

Behind public HTTPS URLs

On a box (boxctl.io) the VM has no public address; each port gets its own HTTPS URL instead. Expose two ports, not one:

boxctl expose graph 7474     # https://graph-aaaaaaaa.boxctl.app -> the Browser
boxctl expose graph 7687     # https://graph-bbbbbbbb.boxctl.app -> Bolt
boxctl expose graph          # list both URLs

Open the URL of port 7474 and fill in the connect form:

Field	Value
Protocol	`bolt+s://`
Connection URL	the host of the port 7687 URL, then `:443`: `graph-bbbbbbbb.boxctl.app:443`
Database	leave empty (the default database, `neo4j`)
Username	`neo4j`
Password	printed by the script; `cat /opt/neo4j/password` on the VM

Three things go wrong here:

The Browser fills in the host of the page with port 7687, e.g. graph-aaaaaaaa.boxctl.app:7687. Nothing listens there. Replace it with the host of the other URL, the one for port 7687.
The port is 443, not 7687: you are connecting to the HTTPS URL, which forwards to 7687 on the VM.
bolt:// and neo4j:// are refused. A page served over HTTPS may only open encrypted connections, so the protocol has to end in +s. Leave https:// out of the connection URL.

Neo4j itself needs no certificate. Bolt on 7687 also speaks WebSocket, which is what the Browser uses, and the URL passes WebSockets through with its own TLS.

To have the Browser fill in the right address by itself, and to make neo4j+s:// work too, tell Neo4j where Bolt is reachable. This restarts the container and keeps the data and the password:

boxctl ssh graph -T 3m -- "curl -fsSL https://templates.onctl.com/neo4j/neo4j.sh | BOLT_ADVERTISED_ADDRESS=graph-bbbbbbbb.boxctl.app:443 bash"

Keep both ports exposed once they are set up. A URL stays the same for as long as its port is exposed, across pause and resume, but boxctl unexpose retires it: exposing the port again gives a new one. After that, the address in the connect form and BOLT_ADVERTISED_ADDRESS both have to be changed to the new 7687 URL.

Anyone who has the URLs can reach the database; the password is all that protects it.

Drivers and cypher-shell on your own machine speak plain TCP Bolt, not WebSocket, so they can't go through an HTTP URL. Forward the port instead, onctl port-forward graph 7687, and use bolt://localhost:7687.

Running it again

Running the script again replaces the container and keeps the data. Neo4j sets the password only when it creates the database, so a later NEO4J_PASSWORD is ignored: the script says so and keeps using the one in /opt/neo4j/password. To change it, run ALTER CURRENT USER SET PASSWORD FROM '<old>' TO '<new>' in the Browser and update that file.

Options

onctl up -n graph -a neo4j/neo4j.sh \
  -e NEO4J_PASSWORD=a-long-password \
  -e NEO4J_VERSION=5.26 \
  -e NEO4J_HOME=/mnt/neo4j

NEO4J_VERSION is an image tag of neo4j on Docker Hub. Add -enterprise for the Enterprise edition, which also needs its licence accepted and isn't set up by this script.

See the template's source for exactly what it runs.