Local Development

Run Nectr locally for development and testing

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

1. Create Virtual Environment

   Create and activate a Python virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
2. 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.

3. Configure Environment Variables

   Copy the example environment file and fill in your values:

   cp .env.example .env
   

   Edit .env and set the required variables:

   Required

   # 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
   
4. 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:

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

   Apply all database migrations:

   alembic upgrade head
   

   This creates all required tables:

   • users
   • installations
   • events
   • workflows
   • oauth_states
6. 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.
   
7. 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

1. Navigate to Frontend Directory

   cd nectr-web
   
2. Install Dependencies

   npm install
   

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

3. 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.

4. 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
   
5. 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:

1. Create GitHub OAuth App

   1. Go to github.com/settings/developers
   2. Click New OAuth App
   3. Fill in the details:
      • Application name: Nectr Local Dev
      • Homepage URL: http://localhost:3000
      • Authorization callback URL: http://localhost:8000/auth/github/callback
   4. Click Register application
2. 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
   
3. Create Personal Access Token

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

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

   Update your backend .env:

   GITHUB_PAT=ghp_your_token
   
4. Test Authentication

   1. Go to http://localhost:3000
   2. Click Sign in with GitHub
   3. Authorize the app
   4. 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:

1. Install ngrok

   Download from ngrok.com or install via package manager:

   brew install ngrok  # macOS
   
2. Start ngrok Tunnel

   ngrok http 8000
   

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

3. Update Environment Variables

   Update your .env temporarily:

   BACKEND_URL=https://abc123.ngrok.io
   
4. Configure GitHub Webhook

   In your GitHub repo settings:

   1. Go to Settings → Webhooks → Add webhook
   2. Set Payload URL: https://abc123.ngrok.io/api/v1/webhooks/github
   3. Set Content type: application/json
   4. Set Secret: (generate a random string)
   5. Select events: Pull requests
   6. Click Add webhook
5. 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