Local Development

This guide covers the complete local development environment setup beyond the Quick Start — including environment variables, Turbo task dependencies, and useful dev scripts.

Prerequisites

• Bun 1.3+ — curl -fsSL https://bun.sh/install | bash
• Docker Desktop 24+ or Docker Engine + Compose v2
• Node.js 20+ (some tooling still requires Node)
• Git 2.40+

Verify:

bun --version        # 1.3.x
docker --version     # 24.x
node --version       # v20.x

Initial Setup

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

# Copy environment template
cp .env.example .env

# Install all workspace dependencies
bun install

# Start core infrastructure (Postgres + Redis)
./scripts/start-dev.sh -d

# Run migrations
bun run db:migrate

# Optional: seed sample data
bun run db:seed

Environment Variables

Key variables for local development (set in .env):

# === Required ===
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/printstudio
REDIS_URL=redis://localhost:6379
SESSION_SECRET=dev-secret-32-chars-minimum-please
API_KEY_SALT=dev-salt-32-chars-minimum-please

# === Stripe (use test keys) ===
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...    # from `stripe listen` output

# === Email (use Resend test or SMTP) ===
RESEND_API_KEY=re_...
# OR
SMTP_HOST=localhost
SMTP_PORT=1025     # Mailpit in Docker for local email testing

# === Optional integrations ===
N8N_URL=http://localhost:5678
N8N_API_KEY=replace-me
OPENCLAW_URL=http://localhost:18789
OPENCLAW_TOKEN=replace-me
MOONRAKER_URL=http://192.168.1.100:7125

# === Feature flags ===
SLICER_MOCK=true       # Skip real OrcaSlicer in dev
TEST_INFRA_SKIP=false  # Set true to skip DB in unit tests

Running Individual Apps

# API only (port 8787)
bun run dev:api
# or: cd apps/print-ops-api && bun dev

# Web only (port 4321)
bun run dev:web
# or: cd apps/web && bun dev

# Plant agent (port 8788)
bun run dev:agent

# Docs site (port 4322)
cd apps/docs && bun dev

Running Everything with Turbo

bun run dev
# Turborepo starts all apps in parallel with hot reload

Turbo respects the task graph in turbo.json — packages are built before apps that depend on them.

Database Operations

# Generate a new migration after schema changes
bun run db:generate

# Apply pending migrations
bun run db:migrate

# Reset and reseed (destroys all data)
docker compose exec postgres psql -U postgres -c "DROP DATABASE printstudio; CREATE DATABASE printstudio;"
bun run db:migrate && bun run db:seed

Drizzle schema files are in packages/core/src/db/schema/. Migrations are in packages/core/src/db/migrations/.

Package Development

When modifying packages/core or packages/integrations:

# Build the package
cd packages/core && bun run build

# Or build all packages in dependency order
bun run build

Changes to packages require a rebuild before apps see them. In development, use bun run --watch in the package directory to auto-rebuild.

Useful Scripts

Script	Description
bun run build	Build all packages and apps
bun run test	Run all tests
bun run typecheck	TypeScript check across monorepo
bun run db:generate	Generate Drizzle migrations
bun run db:migrate	Apply migrations
bun run db:seed	Seed sample data
bun run infra:dev	Start core Docker services (detached)
bun run infra:ecosystem	Start full ecosystem (detached)
bun run test:infra:up	Start test infrastructure
bun run test:infra:down	Stop test infrastructure

Ports Reference

Service	Port
Postgres	5432
Redis	6379
Print Ops API	8787
Plant Agent	8788
Web / Dashboard	4321
Docs	4322
n8n	5678
Grafana	3000
Prometheus	9090
InvenTree	8000

IDE Setup

The monorepo ships with TypeScript references. For VS Code, open the root workspace file and ensure the TypeScript server is using the workspace version (Bun’s TypeScript).

Recommended extensions: ESLint, Prettier, Astro, Tailwind CSS IntelliSense, Drizzle ORM.