Skip to content

Latest commit

 

History

History
217 lines (144 loc) · 3.35 KB

setup.md

File metadata and controls

217 lines (144 loc) · 3.35 KB

Home > Contributing > Development Setup

Development Setup

Set up your local development environment for KnowStack.

Prerequisites

  • Node.js 20+ - JavaScript runtime
  • pnpm - Package manager (npm install -g pnpm)
  • Docker - Container runtime
  • Docker Compose - Multi-container orchestration

Quick Start

# Clone the repository
git clone https://github.com/wellitongervickas/knowstack.git
cd knowstack

# Install dependencies
pnpm install

# Start database and Redis
docker compose up -d db redis

# Configure environment
cp .env.example .env

# Setup database
pnpm prisma generate
pnpm prisma migrate dev

# Start development server
pnpm start:dev

The server runs at http://localhost:3100.

With the server running, seed data using the SDK CLI:

npx @knowstack/sdk --init

See SDK Setup Guide for full options.


Docker Services

# Start all services
docker compose up -d

# Start specific service
docker compose up -d db
docker compose up -d redis

# View logs
docker compose logs -f

# Stop services
docker compose down

Services:

  • db - PostgreSQL 16 on port 5532
  • redis - Redis 7 on port 6479

Environment Variables

Key variables in .env:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5532/knowstack"

# Redis
REDIS_URL="redis://localhost:6479"

# AI Provider (optional)
AI_DEFAULT_PROVIDER="stub"  # or "openai"
OPENAI_API_KEY="sk-..."     # if using OpenAI

See .env.example for all options.


Database

Prisma Commands

# Generate Prisma client
pnpm prisma generate

# Run migrations
pnpm prisma migrate dev

# Reset database (destructive!)
pnpm prisma migrate reset --force

# Open database GUI
pnpm prisma studio

SDK CLI

The SDK CLI connects to the running server via MCP to seed data:

npx @knowstack/sdk --init

The CLI walks you through:

  1. Organization creation (or reuses existing by slug)
  2. Project creation (or reuses existing by slug)
  3. Document ingestion from a local directory
  4. Instruction seeding (agents, skills, commands, templates)
  5. Embedding generation
  6. MCP connection config output

See SDK Setup Guide for full details.


Development Commands

# Start with hot reload
pnpm start:dev

# Build for production
pnpm build

# Start production build
pnpm start:prod

# Run unit tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Type check
pnpm typecheck

# Lint
pnpm lint

IDE Setup

VS Code

Recommended extensions:

  • Prisma - Schema highlighting
  • ESLint - Code linting
  • TypeScript - Language support

Settings

{
  "editor.formatOnSave": true,
  "typescript.preferences.importModuleSpecifier": "non-relative"
}

Troubleshooting

Database connection failed

# Check if PostgreSQL is running
docker compose ps

# Check logs
docker compose logs db

Prisma client out of date

pnpm prisma generate

Port already in use

# Find process using port 3100
lsof -i :3100

# Kill it
kill -9 <PID>

See Also