Skip to content

Local Development Setup

This guide helps you set up TruSpace for active development with hot reload capabilities.

Prerequisites

  • Node.js 20+ (check with node --version)
  • npm 10+ or pnpm
  • Docker 20.10+
  • Docker Compose 2.0+
  • Git

Node Version Manager

We recommend using nvm to manage Node.js versions: 

nvm install 20
nvm use 20

Step 1: Clone and Configure

# Clone the repository
git clone git@github.com:openkfw/TruSpace.git
cd TruSpace

# Copy environment configuration
cp .env.example .env

Step 2: Start Infrastructure Services

Start only the backend services (IPFS, database, AI):

./start.sh --local-frontend

This starts:

  • IPFS node and cluster
  • Backend API server
  • Ollama and Open Web UI (optional)

Step 3: Start Frontend in Dev Mode

In a new terminal:

cd frontend
npm install
npm run dev

The frontend will be available at http://localhost:3000 with hot reload.

Step 4: (Optional) Start Backend in Dev Mode

For backend development with hot reload:

# Start only IPFS and AI services
docker compose up ipfs0 cluster0 ollama webui -d

cd backend
npm install
npm run dev

cd frontend
npm install
npm run dev

Project Structure

TruSpace/
├── backend/                 # Express.js API
│   ├── src/
│   │   ├── routes/         # API endpoints
│   │   ├── services/       # Business logic
│   │   ├── types/          # TypeScript interfaces
│   │   └── index.ts        # Entry point
│   └── package.json
├── frontend/               # Next.js application
│   ├── src/
│   │   ├── app/           # App router pages
│   │   ├── components/    # React components
│   │   └── lib/           # Utilities
│   └── package.json
├── docker-compose.yml      # Main compose file
├── .env.example           # Environment template
└── start.sh               # Startup script

Development Workflow

Running Tests

cd backend
npm test
npm run test:watch  # Watch mode

cd frontend
npm test
npm run test:e2e    # E2E tests

# From root directory
npm test

Linting and Formatting

# Check formatting
npm run lint

# Fix formatting
npm run lint:fix

# Type checking
npm run typecheck

Building for Production

# Build backend
cd backend && npm run build

# Build frontend
cd frontend && npm run build

Debug Configuration

VS Code

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Backend: Debug",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}/backend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "console": "integratedTerminal"
    },
    {
      "name": "Frontend: Debug",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/frontend"
    }
  ]
}

Environment Variables for Development

Create a .env.local in the frontend directory:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_DEBUG=true

Common Issues

Port Conflicts

If ports are already in use:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

Node Modules Issues

# Clear and reinstall
rm -rf node_modules package-lock.json
npm install

Docker Issues

# Reset Docker environment
docker compose down -v
docker system prune -f
./start.sh

Next Steps