Skip to main content
This guide will help you set up StellarStack for local development on your machine.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js 20+

Download from nodejs.org

pnpm 8+

Install with npm install -g pnpm

PostgreSQL 15+

Download from postgresql.org

Docker

Download from docker.com (for daemon testing)
Additionally, you’ll need:
  • Git for version control
  • A code editor (VS Code recommended)

​
Development Setup

1

Fork the repository

Fork the StellarStack repository on GitHub to your account:
# Navigate to:
https://github.com/StellarStackOSS/StellarStack
# Click "Fork" button
2

Clone your fork

Clone your forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/stellarstack.git
cd stellarstack
3

Install dependencies

Install all workspace dependencies using pnpm:
pnpm install
This will:
  • Install dependencies for all apps and packages
  • Set up Git hooks for commit linting
  • Link workspace packages
4

Set up environment variables

Copy the example environment files and configure them:
# API environment
cp apps/api/.env.example apps/api/.env

# Web panel environment
cp apps/web/.env.example apps/web/.env
Configure apps/api/.env:
# Database connection
DATABASE_URL="postgresql://user:password@localhost:5432/stellarstack"

# Authentication secret (generate random 32+ characters)
BETTER_AUTH_SECRET="your-secret-key-here"

# API URL
API_URL="http://localhost:3001"

# Frontend URL
FRONTEND_URL="http://localhost:3000"
Configure apps/web/.env:
# API URL
NEXT_PUBLIC_API_URL="http://localhost:3001"
5

Set up the database

Initialize the PostgreSQL database:
# Navigate to API directory
cd apps/api

# Push schema to database
pnpm db:push

# Generate Prisma client
pnpm db:generate

# Return to root
cd ../..
Make sure PostgreSQL is running and the database specified in DATABASE_URL exists. Create it with:
createdb stellarstack
6

Start development servers

Start all development servers at once:
pnpm dev
This starts:Turborepo will show progress for each service in the terminal UI.

​
Accessing the Panel

Once the development servers are running:

Web Panel

Main application interface

API Server

Backend API endpoints

Documentation

Documentation site

Landing Page

Marketing website

​
Development Workflow

​
Running Individual Services

If you only need to work on specific apps: 
# Run API server only
pnpm --filter @workspace/api dev

# Run web panel only
pnpm --filter web dev

# Run docs only
pnpm --filter docs dev

​
Database Operations

View database schema: 
cd apps/api
pnpx prisma studio
This opens a visual database browser at http://localhost:5555 Create a migration: 
cd apps/api
pnpm db:migrate
Reset database: 
cd apps/api
pnpm db:reset

​
Code Quality Checks

Type checking: 
# Check all packages
pnpm typecheck

# Check specific package
pnpm --filter web typecheck
Linting: 
# Lint all packages
pnpm lint

# Lint specific package
pnpm --filter @workspace/api lint

# Fix linting issues
pnpm lint --fix
Formatting: 
# Format all files
pnpm format

# Check formatting without writing
pnpm format:check

​
Building for Production

Build all apps: 
pnpm build
Build specific app: 
pnpm build:api
pnpm build:web
pnpm build:docs
Start production build locally: 
# Build first
pnpm build

# Start API
pnpm start:api

# Start web (in another terminal)
pnpm start:web

​
Git Workflow

​
Creating a Branch

# Create a new feature branch
git checkout -b feat/STE-123-add-new-feature

# Or without Linear ticket
git checkout -b feat/add-new-feature

​
Making Commits

Commits are automatically validated by Git hooks: 
# Stage changes
git add .

# Commit with conventional format
git commit -m "feat: STE-123 add webhook retry logic"

# Or without Linear ticket
git commit -m "feat: add webhook retry logic"
Automatic Formatting: Git hooks automatically format staged files with Prettier before committing.

​
Keeping Your Fork Updated

# Add upstream remote (one time)
git remote add upstream https://github.com/StellarStackOSS/StellarStack.git

# Fetch latest changes
git fetch upstream

# Rebase your branch
git rebase upstream/main

​
Testing Your Changes

Before submitting a pull request:
1

Run type checking

pnpm typecheck
Ensure no TypeScript errors.
2

Run linting

pnpm lint
Fix any linting issues.
3

Test in development

pnpm dev
Manually test your changes in the development environment.
4

Test production build

pnpm build
pnpm start:api &
pnpm start:web
Verify your changes work in production mode.

​
Troubleshooting

​
Port Already in Use

If you get “port already in use” errors: 
# Find and kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
PORT=3005 pnpm dev

​
Database Connection Issues

Verify PostgreSQL is running: 
pg_isready
Check connection string: Ensure DATABASE_URL in apps/api/.env is correct: 
DATABASE_URL="postgresql://user:password@localhost:5432/stellarstack"
Reset database: 
cd apps/api
pnpm db:reset

​
Dependency Issues

Clear and reinstall: 
# Remove all node_modules
rm -rf node_modules apps/*/node_modules packages/*/node_modules

# Clear pnpm cache
pnpm store prune

# Reinstall
pnpm install

​
Build Errors

Clear Turborepo cache: 
pnpm turbo clean
Clear Next.js cache: 
rm -rf apps/web/.next
rm -rf apps/home/.next

​
Type Generation Issues

If TypeScript can’t find types: 
# Regenerate Prisma client
cd apps/api
pnpm db:generate

# Rebuild all packages
cd ../..
pnpm build

​
Docker Development (Optional)

For testing the full stack with Docker: 
# Start all services with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

​
IDE Setup (VS Code)

Recommended extensions:
  • ESLint: dbaeumer.vscode-eslint
  • Prettier: esbenp.prettier-vscode
  • Prisma: Prisma.prisma
  • Tailwind CSS IntelliSense: bradlc.vscode-tailwindcss
  • TypeScript: Built-in
Workspace settings (.vscode/settings.json): 
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

​
Next Steps

Now that you have a local development environment:

Architecture

Learn how StellarStack is architected

Monorepo Structure

Understand the monorepo organization

Contributing

Read the contribution guidelines

API Reference

Explore the API documentation

​
Getting Help

If you encounter issues:
  • GitHub Issues: Report bugs or ask questions
  • GitHub Discussions: Community help and discussions
  • Discord: Real-time chat with contributors
  • Linear: Track development progress at linear.app/stellarstack

Build docs developers (and LLMs) love

Get started for freeTalk to us