Development Setup

This guide covers everything you need to run OpenScouter locally, from installing prerequisites to starting the development server.

Prerequisites

You need Node.js 20 or later. The project uses features available only in Node 20+, so older versions will not work.

The recommended way to manage Node versions is nvm:

nvm install 20
nvm use 20
node --version   # should print v20.x.x or later

You also need npm 10+, which ships with Node 20. Verify with npm --version.

Cloning the Repository

git clone https://github.com/your-org/openscouter.git
cd openscouter

If you are contributing as an external collaborator, fork the repository first and clone your fork instead. See Contributing for fork-based workflow details.

Installing Dependencies

npm install

This installs all runtime and development dependencies. Do not use --legacy-peer-deps or --force unless you have raised the issue with the team first.

Environment Variables

Create a .env.local file in the project root. This file is listed in .gitignore and will never be committed.

Copy the example template to get started:

cp .env.example .env.local

Fill in the values for your local setup. The table below describes every variable:

Variable	Description	Required	Example
`DATABASE_URL`	PostgreSQL connection string	Yes	`postgresql://user:pass@localhost:5432/openscouter`
`NEXTAUTH_SECRET`	Secret for NextAuth.js signing	Yes	A 32-character random string
`NEXTAUTH_URL`	Base URL for OAuth callbacks	Yes	`http://localhost:3000`
`OPENAI_API_KEY`	OpenAI API key for the AI analysis pipeline	Yes	`sk-...`
`ANTHROPIC_API_KEY`	Anthropic API key for the AI analysis pipeline	No	`sk-ant-...`
`GOOGLE_AI_API_KEY`	Google Gemini API key for the AI analysis pipeline	No	`AIza...`
`STRIPE_SECRET_KEY`	Stripe secret key for payout processing	Yes	`sk_test_...`
`STRIPE_WEBHOOK_SECRET`	Stripe webhook signing secret	Yes	`whsec_...`
`TELEGRAM_BOT_TOKEN`	Token for the Telegram bot integration	No	`123456:ABC-DEF...`
`S3_BUCKET_NAME`	S3-compatible bucket for note attachments	No	`openscouter-dev`
`S3_REGION`	AWS region for the S3 bucket	No	`eu-west-1`
`S3_ACCESS_KEY_ID`	AWS access key ID for S3	No	`AKIAIOSFODNN7EXAMPLE`
`S3_SECRET_ACCESS_KEY`	AWS secret access key for S3	No	`wJalrXUtnFEMI/K7MDENG/...`
`LOG_LEVEL`	Logging verbosity	No	`debug`

Variables marked Yes must be set before the dev server will start. Optional variables enable specific features. If they are absent, those features degrade gracefully.

Never commit .env.local or any file containing real credentials.

Starting the Development Server

npm run dev

The application starts at http://localhost:3000. Hot module replacement is enabled, so most changes take effect without a manual reload.

API routes are available under http://localhost:3000/api/.

Building for Production

To verify the production build locally before deploying:

npm run build
npm run start

npm run build compiles TypeScript, bundles assets, and runs build-time validations. Fix any TypeScript or build errors before opening a pull request.

Linting and Formatting

Run these checks locally before pushing:

npm run lint        # ESLint
npm run lint:fix    # ESLint with auto-fix
npm run format      # Prettier
npm run typecheck   # TypeScript compiler check (no emit)

The CI pipeline runs all of these on every pull request. Passing them locally first saves time.