Local Development

Overview

This guide walks you through setting up Nectr for local development. You’ll run the FastAPI backend and Next.js frontend on your machine with hot-reload for rapid iteration.

Prerequisites

Ensure you have these installed:

Python 3.14+ (download)
Node.js 20+ and npm (download)
Git (download)
PostgreSQL (or use a cloud provider like Supabase)
Neo4j (local or AuraDB free tier)

Clone Repository

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

Backend Setup

Create Virtual Environment

Create and activate a Python virtual environment:

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

Install Dependencies

Install all required Python packages:

pip install -r requirements.txt

This installs FastAPI, Uvicorn, SQLAlchemy, Neo4j driver, Anthropic SDK, and all other dependencies.

Configure Environment Variables

Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env and set the required variables:

# AI
ANTHROPIC_API_KEY=sk-ant-...

# Database (local or Supabase)
DATABASE_URL=postgresql+asyncpg://localhost:5432/nectr

# GitHub OAuth App
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_PAT=ghp_...  # Classic token with 'repo' scope

# Auth
SECRET_KEY=your-generated-secret

# Neo4j (local or AuraDB)
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

# Mem0
MEM0_API_KEY=m0-...

# Local URLs
BACKEND_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000

# Environment
APP_ENV=development
DEBUG=True
LOG_LEVEL=DEBUG

Set Up Local PostgreSQL

If using local PostgreSQL:

# Create database
createdb nectr

# Update .env
DATABASE_URL=postgresql+asyncpg://localhost:5432/nectr

Or use Supabase for a cloud database:

Create a free project at supabase.com
Get the connection string from Settings → Database
Use the Session Mode pooler (port 5432)

Run Database Migrations

Apply all database migrations:

alembic upgrade head

This creates all required tables:

users
installations
events
workflows
oauth_states

Start Backend Server

Run the FastAPI backend with hot-reload:

uvicorn app.main:app --reload --port 8000

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Verify Backend

Test the health endpoint:

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "neo4j": "connected",
  "uptime_seconds": 5.23
}

Frontend Setup

Navigate to Frontend Directory

cd nectr-web

Install Dependencies

npm install

This installs Next.js 15, React 19, TailwindCSS 4, and all other dependencies.

Configure Environment

Copy the example environment file:

cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

Do NOT include a trailing slash in NEXT_PUBLIC_API_URL.

Start Development Server

npm run dev

The Next.js dev server starts on port 3000:

▲ Next.js 15.0.0
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 2.3s

Access Frontend

Open your browser and navigate to:

http://localhost:3000

You should see the Nectr landing page.

GitHub OAuth Setup

To test authentication locally:

Create GitHub OAuth App

Go to github.com/settings/developers
Click New OAuth App
Fill in the details:
- Application name: Nectr Local Dev
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:8000/auth/github/callback
Click Register application

Get Credentials

Copy the Client ID and generate a Client Secret.Update your backend .env:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

Create Personal Access Token

Create a classic token at github.com/settings/tokens:

Click Generate new token → Classic
Select scope: repo (full control of private repositories)
Generate and copy the token

Update your backend .env:

GITHUB_PAT=ghp_your_token

Test Authentication

Go to http://localhost:3000
Click Sign in with GitHub
Authorize the app
You should be redirected to /dashboard

Development Workflow

Hot Reload

Both backend and frontend support hot-reload:

Backend: Uvicorn automatically restarts when you edit Python files
Frontend: Next.js Fast Refresh updates the browser instantly

Project Structure

Nectr/
├── app/                    # FastAPI backend
│   ├── main.py            # Entry point
│   ├── core/              # Config, database, Neo4j
│   ├── models/            # SQLAlchemy models
│   ├── api/v1/            # API routes
│   ├── auth/              # Authentication
│   ├── services/          # Business logic
│   ├── integrations/      # GitHub, MCP
│   └── mcp/               # MCP server & client
├── alembic/               # Database migrations
├── nectr-web/             # Next.js frontend
│   └── src/
│       ├── app/           # App Router pages
│       ├── components/    # React components
│       ├── hooks/         # Custom hooks
│       └── lib/           # API client
├── requirements.txt       # Python dependencies
└── .env                   # Backend environment

Common Development Tasks

Create a new database migration

alembic revision --autogenerate -m "Add new column"
alembic upgrade head

Reset database

alembic downgrade base
alembic upgrade head

Test API endpoints

Use curl or tools like Postman/Insomnia:

# Get current user
curl http://localhost:8000/auth/me -H "Cookie: token=your_jwt"

# List repos
curl http://localhost:8000/api/v1/repos -H "Cookie: token=your_jwt"

View logs

Backend logs appear in the terminal where you ran uvicorn. Increase verbosity:

LOG_LEVEL=DEBUG uvicorn app.main:app --reload

Run type checks

# Backend
mypy app/

# Frontend
cd nectr-web
npm run type-check

Testing Webhooks Locally

GitHub webhooks require a public URL. Use ngrok to expose your local server:

Install ngrok

Download from ngrok.com or install via package manager:

brew install ngrok  # macOS

Start ngrok Tunnel

ngrok http 8000

Copy the public URL (e.g., https://abc123.ngrok.io).

Update Environment Variables

Update your .env temporarily:

BACKEND_URL=https://abc123.ngrok.io

Configure GitHub Webhook

In your GitHub repo settings:

Go to Settings → Webhooks → Add webhook
Set Payload URL: https://abc123.ngrok.io/api/v1/webhooks/github
Set Content type: application/json
Set Secret: (generate a random string)
Select events: Pull requests
Click Add webhook

Test Webhook

Open or update a PR in your repo. Check the backend logs to see the webhook event.

Troubleshooting

Port already in use

If port 8000 or 3000 is in use:

# Backend (different port)
uvicorn app.main:app --reload --port 8001

# Frontend (different port)
PORT=3001 npm run dev

Update NEXT_PUBLIC_API_URL and FRONTEND_URL accordingly.

Database connection errors

Ensure PostgreSQL is running:

# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql

Verify connection string in .env.

Neo4j connection errors

If using local Neo4j:

# Start Neo4j
neo4j start

# Check status
neo4j status

Verify URI in .env: bolt://localhost:7687

Module import errors

Ensure virtual environment is activated and dependencies are installed:

source venv/bin/activate
pip install -r requirements.txt

CORS errors in browser

Verify FRONTEND_URL is set correctly in backend .env:

FRONTEND_URL=http://localhost:3000

CORS middleware in app/main.py allows requests from this URL.

Next Steps

Deploy to Railway

Deploy the backend to production

Deploy to Vercel

Deploy the frontend to production

Getting Started

Core Features

Integrations

Configuration

Deployment

Overview

Prerequisites

Clone Repository

Backend Setup

Frontend Setup

GitHub OAuth Setup

Development Workflow

Hot Reload

Project Structure

Common Development Tasks

Testing Webhooks Locally

Troubleshooting

Next Steps

Deploy to Railway

Deploy to Vercel

Build docs developers (and LLMs) love

Getting Started

Core Features

Integrations

Configuration

Deployment

Documentation Index

​Overview

​Prerequisites

​Clone Repository

​Backend Setup

​Frontend Setup

​GitHub OAuth Setup

​Development Workflow

​Hot Reload

​Project Structure

​Common Development Tasks

​Testing Webhooks Locally

​Troubleshooting

​Next Steps

Deploy to Railway

Deploy to Vercel

Build docs developers (and LLMs) love

Overview

Prerequisites

Clone Repository

Backend Setup

Frontend Setup

GitHub OAuth Setup

Development Workflow

Hot Reload

Project Structure

Common Development Tasks

Testing Webhooks Locally

Troubleshooting

Next Steps