Environment Setup Guide¶

Version: 1.0
Date: January 18, 2026
Status: Active

This guide walks you through setting up a local development environment for Forma3D.Connect.

Prerequisites¶

Ensure you have the following installed:

Tool	Version	Installation
Node.js	20.x LTS	nodejs.org or use nvm
pnpm	9.x	`corepack enable && corepack prepare pnpm@9 --activate`
PostgreSQL	16.x	postgresql.org or Docker
Docker	Latest	docker.com (optional, but recommended)
Git	Latest	git-scm.com
K6	Latest	k6.io (for load testing)

Verify Prerequisites¶

# Check Node.js version
node --version  # Should be v20.x.x

# Check pnpm version
pnpm --version  # Should be 9.x.x

# Check PostgreSQL (if installed locally)
psql --version  # Should be 16.x

# Check Docker
docker --version

# Check Git
git --version

Quick Start¶

1. Clone Repository¶

# Clone via HTTPS
git clone https://YOUR_ORG@dev.azure.com/YOUR_ORG/forma-3d-connect/_git/forma-3d-connect

# Or clone via SSH
git clone git@ssh.dev.azure.com:v3/YOUR_ORG/forma-3d-connect/forma-3d-connect

# Navigate to project directory
cd forma-3d-connect

2. Install Dependencies¶

# Install all dependencies (also generates Prisma client)
pnpm install

3. Configure Environment¶

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your configuration

Edit .env with the following configuration:

# =============================================================================
# DATABASE
# =============================================================================
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/forma3d_connect?schema=public"

# =============================================================================
# APPLICATION
# =============================================================================
NODE_ENV="development"
APP_PORT=3000
APP_URL="http://localhost:3000"
FRONTEND_URL="http://localhost:4200"

# =============================================================================
# SHOPIFY INTEGRATION
# =============================================================================
SHOPIFY_SHOP_DOMAIN="your-shop.myshopify.com"
SHOPIFY_API_VERSION="2024-01"
SHOPIFY_API_KEY="your-api-key"
SHOPIFY_API_SECRET="your-api-secret"
SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"
SHOPIFY_WEBHOOK_SECRET="your-webhook-secret"

# =============================================================================
# SIMPLYPRINT INTEGRATION (optional for development)
# =============================================================================
SIMPLYPRINT_API_URL="https://api.simplyprint.io/v1"
SIMPLYPRINT_API_KEY="your-api-key"
SIMPLYPRINT_COMPANY_ID="your-company-id"
SIMPLYPRINT_WEBHOOK_SECRET="your-webhook-secret"

# =============================================================================
# SENDCLOUD INTEGRATION (optional for development)
# =============================================================================
SHIPPING_ENABLED=false
SENDCLOUD_PUBLIC_KEY="your-public-key"
SENDCLOUD_SECRET_KEY="your-secret-key"
SENDCLOUD_API_URL="https://panel.sendcloud.sc/api/v2"
DEFAULT_SHIPPING_METHOD_ID=8
DEFAULT_SENDER_ADDRESS_ID=12345

# =============================================================================
# OBSERVABILITY (optional for development)
# =============================================================================
# SENTRY_DSN="https://your-dsn@sentry.io/project-id"

# =============================================================================
# ADMIN API KEY
# =============================================================================
# Generate with: openssl rand -hex 32
INTERNAL_API_KEY="your-development-api-key"

# =============================================================================
# RATE LIMITING (optional, defaults shown)
# =============================================================================
# RATE_LIMIT_TTL_SECONDS=60
# RATE_LIMIT_DEFAULT=10000
# RATE_LIMIT_WEBHOOK=100

4. Set Up Database¶

Option A: Docker (Recommended)¶

# Start PostgreSQL container
docker run --name forma3d-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=forma3d_connect \
  -p 5432:5432 \
  -d postgres:16

# Verify container is running
docker ps

# Run database migrations
pnpm db:migrate

# (Optional) Seed the database with test data
pnpm db:seed

Option B: Local PostgreSQL¶

# Create the database
createdb forma3d_connect

# Run database migrations
pnpm db:migrate

# (Optional) Seed with test data
pnpm db:seed

5. Start Development Servers¶

# Start both API and Web simultaneously
pnpm dev

# API will be available at: http://localhost:3000
# Web will be available at: http://localhost:4200

Or start services individually:

# Terminal 1: Start Backend API
pnpm api:dev

# Terminal 2: Start Frontend Web
pnpm web:dev

6. Verify Installation¶

# Test API health endpoint
curl http://localhost:3000/health
# Expected: {"status":"ok","database":"connected",...}

# Test dependencies health (will show disabled integrations)
curl http://localhost:3000/health/dependencies

# Open Swagger API documentation
open http://localhost:3000/api/docs

# Open frontend in browser
open http://localhost:4200

Database Management¶

Prisma Commands¶

# Create a new migration
pnpm db:migrate

# Apply migrations to database
pnpm db:migrate:deploy

# Reset database (drop, create, migrate, seed)
pnpm prisma migrate reset

# Open Prisma Studio (visual database browser)
pnpm db:studio
# Opens at http://localhost:5555

# Regenerate Prisma client
pnpm prisma generate

# Generate ERD diagram
pnpm db:erd
# Outputs: prisma/ERD.puml

Testing¶

Run Tests¶

# Run all unit tests
pnpm test

# Run tests with coverage
pnpm nx test api --coverage
pnpm nx test web --coverage

# Run E2E tests
pnpm test:e2e

# Run acceptance tests (requires staging or local deployment)
pnpm nx run acceptance-tests:test --configuration=local

Run Load Tests¶

# Install k6 first (if not installed)
brew install k6  # macOS
# or see https://k6.io/docs/get-started/installation/

# Run load tests against local
pnpm load-test:local

# Run dashboard load test
pnpm load-test:dashboard

Development with Webhooks¶

To receive Shopify webhooks locally, use ngrok:

# Install ngrok
brew install ngrok  # macOS

# Start tunnel to local API
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
# Update webhook URL in Shopify admin

Common Issues¶

Port Already in Use¶

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 pnpm api:dev

Database Connection Issues¶

# Check if PostgreSQL is running
docker ps | grep postgres  # If using Docker
pg_isready                 # If installed locally

# Verify connection string
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1"

Prisma Client Not Generated¶

# Regenerate Prisma client
pnpm prisma generate

# If still failing, clean and reinstall
rm -rf node_modules
pnpm install

Nx Cache Issues¶

# Clear Nx cache
pnpm nx reset

IDE Configuration¶

VS Code Extensions (Recommended)¶

ESLint - Linting
Prettier - Code formatting
Prisma - Schema syntax highlighting
PlantUML - Diagram preview
REST Client - API testing
GitLens - Git integration

VS Code Settings¶

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "relative"
}

Next Steps¶

Review the README.md for project overview
Explore the API documentation in Swagger UI
Read the Architecture documentation
Check the Implementation Plan for current status

Revision History:

Version	Date	Author	Changes
1.0	2026-01-18	Phase 6 Implementation	Initial guide