Skip to content
Klutch.sh Docs

Deploying a Neo4j App

Introduction

Neo4j is a leading open-source graph database optimized for connected data and Cypher queries. Deploying Neo4j with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for your graph data—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample client usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Dockerfile (GitHub is the only supported git source)
  • TLS certificates if you plan to secure the bolt/http endpoints
  • Sizing for persistent storage of graph data and logs

For onboarding, see the Quick Start.

Architecture and ports

  • Bolt protocol: internal port 7687 (TCP).
  • HTTP API/browser: internal port 7474 (HTTP).
  • Choose TCP traffic and set the internal port to 7687 for Bolt clients; optionally expose HTTP on 7474 if needed.
  • Persistent storage is required for data and logs.

Repository layout

neo4j/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets (Neo4j password, TLS keys) out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t neo4j-local .
docker run -p 7687:7687 -p 7474:7474 \
  -e NEO4J_AUTH=neo4j/testpass \
  neo4j-local

Dockerfile for Neo4j (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM neo4j:5.18


ENV NEO4J_dbms_default__listen__address=0.0.0.0 \
    NEO4J_dbms_default__advertised__address=0.0.0.0 \
    NEO4J_AUTH=none


EXPOSE 7474 7687
CMD ["neo4j"]

Notes:

  • Pin the image tag (e.g., 5.18.x) for stability; update intentionally.
  • Set NEO4J_AUTH=neo4j/<password> for production; avoid none outside testing.
  • Add TLS by mounting certs and setting NEO4J_dbms_ssl_policy_bolt_enabled=true and related paths.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • NEO4J_AUTH=neo4j/<strong-password>
  • NEO4J_dbms_default__listen__address=0.0.0.0
  • NEO4J_dbms_default__advertised__address=example-app.klutch.sh
  • Optional TLS: NEO4J_dbms_ssl_policy_bolt_enabled=true, NEO4J_dbms_ssl_policy_bolt_private__key=/certs/bolt.key, NEO4J_dbms_ssl_policy_bolt_public__certificate=/certs/bolt.crt
  • Optional tuning: NEO4J_dbms_memory_pagecache_size, NEO4J_server_memory_heap_initial__size, NEO4J_server_memory_heap_max__size

If you deploy without the Dockerfile and need Nixpacks overrides (not typical for Neo4j):

  • NIXPACKS_START_CMD=neo4j

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /data — database files.
  • /logs — log files.
  • /certs — optional TLS certificates.

Ensure these directories are writable.

Deploy Neo4j on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select TCP traffic and set the internal port to 7687 (Bolt). Expose HTTP on 7474 only if required.
  4. Add the environment variables above, including NEO4J_AUTH and any tuning/TLS settings.
  5. Attach persistent volumes for /data, /logs, and /certs (if using TLS) sized for your dataset and retention needs.
  6. Deploy. Connect Bolt clients to bolt://example-app.klutch.sh:8000 (mapped to internal 7687); access the HTTP browser at https://example-app.klutch.sh:7474 if exposed.

Sample client usage (JavaScript)

import neo4j from "neo4j-driver";


const driver = neo4j.driver(
  "bolt://example-app.klutch.sh:8000",
  neo4j.auth.basic("neo4j", "<password>")
);
const session = driver.session();


await session.run("CREATE (n:Hello {name: $name}) RETURN n", { name: "Klutch" });
const result = await session.run("MATCH (n:Hello) RETURN n.name AS name");
console.log(result.records[0].get("name"));


await session.close();
await driver.close();

Health checks and production tips

  • Add a TCP probe on port 7687; for HTTP, probe / on 7474 if exposed.
  • Enforce TLS in production; keep certs in volumes and rotate them regularly.
  • Monitor disk usage on /data and /logs; resize before they fill.
  • Pin image versions and back up data before upgrades; test upgrades in staging.
  • Tune heap and pagecache sizes based on workload and memory limits.

Neo4j on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, Bolt port 7687 configured, and data directories persisted, you can run connected-data workloads without extra YAML or workflow overhead.