Skip to main content

​
Prerequisites

  • Python 3.14+ (backend)
  • Node.js 20+ (frontend)
  • PostgreSQL database (Supabase free tier recommended)
  • Neo4j database (Neo4j Aura free tier recommended)
  • Anthropic API key
  • GitHub OAuth App credentials
  • GitHub Personal Access Token (classic, with repo scope)

​
Backend Setup

1

Clone the repository

git clone https://github.com/yourusername/nectr.git
cd nectr
2

Create virtual environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
3

Install Python dependencies

pip install -r requirements.txt
Key dependencies:
  • fastapi==0.129.0 - Web framework
  • uvicorn==0.41.0 - ASGI server
  • anthropic==0.83.0 - Claude AI SDK
  • asyncpg==0.31.0 - PostgreSQL async driver
  • neo4j>=5.0 - Neo4j graph database driver
  • mem0ai>=0.1.98 - Semantic memory layer
  • alembic==1.18.4 - Database migrations
  • mcp>=1.0.0 - Model Context Protocol
4

Configure environment variables

Copy the example environment file and fill in required values:
cp .env.example .env
Edit .env and set the required values. See Environment Variables for details.
Generate a secure SECRET_KEY with:
python -c "import secrets; print(secrets.token_hex(32))"
5

Set up GitHub OAuth App

  1. Go to github.com/settings/developers
  2. Click New OAuth App
  3. Fill in:
    • Application name: Nectr Local
    • Homepage URL: http://localhost:3000
    • Authorization callback URL: http://localhost:8000/auth/github/callback
  4. Copy the Client ID and Client Secret to your .env file
6

Create GitHub Personal Access Token

  1. Go to github.com/settings/tokens
  2. Click Generate new token (classic)
  3. Select scope: repo (full control of private repositories)
  4. Copy the token and set it as GITHUB_PAT in .env
This token is used to post PR review comments. Keep it secure and never commit it to git.
7

Run database migrations

Alembic migrations run automatically on startup, but you can run them manually:
alembic upgrade head
8

Start the backend server

uvicorn app.main:app --reload --port 8000
The backend will be available at http://localhost:8000
On startup, Nectr automatically:
  • Runs Alembic migrations
  • Creates PostgreSQL tables
  • Initializes Neo4j schema (constraints and indexes)
  • Scans any connected repos not yet indexed in Neo4j

​
Frontend Setup

1

Navigate to frontend directory

cd nectr-web
2

Install dependencies

npm install
Key dependencies:
  • [email protected] - React framework
  • [email protected] - UI library
  • @tanstack/react-query@^5.90.21 - Data fetching
  • axios@^1.13.6 - HTTP client
  • recharts@^3.7.0 - Analytics charts
  • tailwindcss@^4 - Styling
3

Configure frontend environment

cp .env.example .env.local
Edit .env.local and set:
NEXT_PUBLIC_API_URL=http://localhost:8000
4

Start the development server

npm run dev
The frontend will be available at http://localhost:3001 (Next.js dev server runs on port 3001 by default in this setup)
The dev server uses Turbopack for faster builds. To use webpack instead, remove the --turbopack flag from the dev script in package.json.

​
Verify Installation

  1. Backend health check: 
    curl http://localhost:8000/health
    Expected response: 
    {
  "status": "healthy",
  "service": "Nectr",
  "version": "0.2.0",
  "environment": "development",
  "uptime_seconds": 42.3,
  "database": "healthy",
  "neo4j": "healthy"
}
  2. Frontend: Navigate to http://localhost:3001 and click Sign in with GitHub
  3. OAuth flow: You should be redirected to GitHub, then back to the dashboard

​
Development Workflow

​
Hot Reload

Both backend and frontend support hot reload:
  • Backend: Uvicorn auto-reloads on .py file changes
  • Frontend: Next.js Turbopack reloads on .tsx/.ts file changes

​
Database Changes

When you modify SQLAlchemy models: 
# Generate a new migration
alembic revision --autogenerate -m "description of changes"

# Apply the migration
alembic upgrade head

​
Neo4j Schema Changes

Edit app/core/neo4j_schema.py to add new constraints or indexes. They will be applied on next server restart.

​
Debugging

  • Backend logs: Check the terminal where uvicorn is running
  • Set log level: Change LOG_LEVEL=DEBUG in .env
  • Frontend console: Open browser DevTools → Console
  • Network requests: DevTools → Network tab (filter by “Fetch/XHR”)

​
Common Issues

  • Verify DATABASE_URL in .env is correct
  • Check that PostgreSQL is running and accessible
  • For Supabase: use Session Mode connection string (port 5432)
  • Verify NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD in .env
  • Ensure Neo4j Aura database is running
  • Check that your IP is whitelisted in Neo4j Aura console
  • Verify GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in .env
  • Check that the OAuth callback URL in GitHub settings matches http://localhost:8000/auth/github/callback
  • Ensure BACKEND_URL and FRONTEND_URL in .env are correct
  • Verify FRONTEND_URL in backend .env matches your frontend URL
  • Check that NEXT_PUBLIC_API_URL in frontend .env.local matches backend URL
  • Ensure cookies are enabled in your browser
  • Verify ANTHROPIC_API_KEY in .env is valid
  • Check your API key has sufficient credits at console.anthropic.com
  • Ensure ANTHROPIC_MODEL=claude-sonnet-4-5-20250929 is set

​
Next Steps

Environment Variables

Complete reference of all environment variables

Architecture

Understand how Nectr is built

Deployment

Deploy to Railway and Vercel

Database Setup

PostgreSQL and Neo4j configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us