Documentation Deployment Guide

This guide explains how to build and deploy the neo4j-agent-memory documentation.

Local Development

Prerequisites

  • Node.js 18+ installed

  • npm or yarn

Setup

# Install dependencies
cd docs
npm install

# Build documentation
npm run build

# Or use Makefile from project root
make docs-install
make docs

Development Server

Run with live reload for development:

npm run serve
# Opens http://localhost:8080 with auto-refresh

Or use the Makefile:

make docs-serve

Output

Built documentation is output to docs/_site/.

Deploying to Vercel

Option 1: Deploy from GitHub (Recommended)

  1. Connect Repository to Vercel

    • Go to vercel.com and sign in

    • Click "Add New Project"

    • Import your GitHub repository

  2. Configure Project Settings

    • Root Directory: neo4j-agent-memory/docs

    • Framework Preset: Other

    • Build Command: npm run build

    • Output Directory: _site

    • Install Command: npm install

  3. Deploy

    • Click "Deploy"

    • Vercel will automatically deploy on every push to main

Option 2: Deploy via Vercel CLI

  1. Install Vercel CLI

    npm install -g vercel

  2. Login to Vercel

    vercel login

  3. Deploy from docs directory

    cd docs
vercel

  4. For production deployment

    vercel --prod

Option 3: One-Click Deploy

Deploy with Vercel

Vercel Configuration

The vercel.json file configures:

Clean URLs

URLs work without .html extension:

  • https://docs.example.com/getting-started → getting-started.html

  • https://docs.example.com/faq → faq.html

Redirects

  • /docs → / (redirect docs prefix to root)

  • /docs/page → /page (handle any docs/ prefixed URLs)

Caching

  • Static assets (CSS) cached for 1 year

  • HTML pages use Vercel’s default caching

Security Headers

  • X-Content-Type-Options: nosniff

  • X-Frame-Options: DENY

  • X-XSS-Protection: 1; mode=block

Custom Domain

To use a custom domain like docs.neo4j-agent-memory.dev:

  1. Go to your Vercel project settings

  2. Navigate to "Domains"

  3. Add your custom domain

  4. Configure DNS as instructed by Vercel

Environment Variables

No environment variables are required for the documentation build.

If you need to customize the build, you can set:

Variable Description Default

DOCS_BASE_URL

Base URL for the docs site

/

DOCS_VERSION

Version shown in navigation

Current version

Application Environment Variables

When deploying applications using neo4j-agent-memory, you may need these environment variables:

Variable Description Required

NAM_NEO4J__URI

Neo4j connection URI

Yes

NAM_NEO4J__USERNAME

Neo4j username

Yes

NAM_NEO4J__PASSWORD

Neo4j password

Yes

OPENAI_API_KEY

OpenAI API key (for embeddings/LLM)

Recommended

OPIK_API_KEY

Opik API key (for observability)

Optional

OTEL_EXPORTER_OTLP_ENDPOINT

OpenTelemetry endpoint

Optional

See Configuration Reference for all available settings.

Automatic Deployments

With GitHub integration, Vercel automatically:

  • Production Deploy: On push to main branch

  • Preview Deploy: On pull requests

Each PR gets a unique preview URL for reviewing documentation changes.

Troubleshooting

Build Fails

  1. Check Node.js version (requires 18+)

    node --version

  2. Clear node_modules and reinstall

    rm -rf node_modules package-lock.json
npm install

  3. Test build locally

    npm run build

404 Errors on Clean URLs

Ensure vercel.json has the rewrite rule:

{
  "rewrites": [
    {
      "source": "/:path((?!.*\\.).*)",
      "destination": "/:path.html"
    }
  ]
}

CSS Not Loading

  1. Check that assets/style.css exists

  2. Verify the build copies it to _site/style.css

  3. Check browser console for 404 errors

CI/CD Integration

GitHub Actions

Add to .github/workflows/docs.yml:

name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'neo4j-agent-memory/docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install and Build
        working-directory: neo4j-agent-memory/docs
        run: |
          npm ci
          npm run build

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          working-directory: neo4j-agent-memory/docs
          vercel-args: '--prod'

Required secrets:

  • VERCEL_TOKEN: From Vercel account settings

  • VERCEL_ORG_ID: From .vercel/project.json after vercel link

  • VERCEL_PROJECT_ID: From .vercel/project.json after vercel link

Alternative Platforms

The documentation can also be deployed to:

Netlify

Create netlify.toml in docs directory:

[build]
  command = "npm run build"
  publish = "_site"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

GitHub Pages

Use GitHub Actions to build and deploy to gh-pages branch.

Cloudflare Pages

Similar to Vercel - connect repo and set:

  • Build command: npm run build

  • Output directory: _site