Home > Contributing > Development Setup
Set up your local development environment for KnowStack.
- Node.js 20+ - JavaScript runtime
- pnpm - Package manager (
npm install -g pnpm) - Docker - Container runtime
- Docker Compose - Multi-container orchestration
# 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:devThe server runs at http://localhost:3100.
With the server running, seed data using the SDK CLI:
npx @knowstack/sdk --initSee SDK Setup Guide for full options.
# 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 downServices:
db- PostgreSQL 16 on port 5532redis- Redis 7 on port 6479
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 OpenAISee .env.example for all options.
# 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 studioThe SDK CLI connects to the running server via MCP to seed data:
npx @knowstack/sdk --initThe CLI walks you through:
- Organization creation (or reuses existing by slug)
- Project creation (or reuses existing by slug)
- Document ingestion from a local directory
- Instruction seeding (agents, skills, commands, templates)
- Embedding generation
- MCP connection config output
See SDK Setup Guide for full details.
# 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 lintRecommended extensions:
- Prisma - Schema highlighting
- ESLint - Code linting
- TypeScript - Language support
{
"editor.formatOnSave": true,
"typescript.preferences.importModuleSpecifier": "non-relative"
}# Check if PostgreSQL is running
docker compose ps
# Check logs
docker compose logs dbpnpm prisma generate# Find process using port 3100
lsof -i :3100
# Kill it
kill -9 <PID>- Adding Features - Development guide
- Architecture - Code structure
- Patterns - Conventions