cmdb-insight/docs/Setup and configuration/LOCAL-DEVELOPMENT-SETUP.md

Local Development Setup

PostgreSQL Only (Recommended for Local Development)

Voor lokale development heb je alleen PostgreSQL nodig. De backend en frontend draaien lokaal op je MacBook.

Start PostgreSQL

# Start alleen PostgreSQL
docker-compose -f docker-compose.dev.yml up -d

# Check status
docker-compose -f docker-compose.dev.yml ps

# Check logs
docker-compose -f docker-compose.dev.yml logs -f postgres

Connection String

DATABASE_TYPE=postgres
DATABASE_URL=postgresql://cmdb:cmdb-dev@localhost:5432/cmdb_insight

Of individuele variabelen:

DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=cmdb_insight
DATABASE_USER=cmdb
DATABASE_PASSWORD=cmdb-dev

Stop PostgreSQL

docker-compose -f docker-compose.dev.yml down

Reset Database

# Stop en verwijder volume
docker-compose -f docker-compose.dev.yml down -v

# Start opnieuw
docker-compose -f docker-compose.dev.yml up -d

Connect to Database

# Via psql
docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -d cmdb_insight

# Of direct
psql postgresql://cmdb:cmdb-dev@localhost:5432/cmdb_insight

Useful Commands

# List databases
docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -c "\l"

# List tables
docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -d cmdb_insight -c "\dt"

# Check database size
docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -d cmdb_insight -c "
  SELECT pg_size_pretty(pg_database_size('cmdb_insight')) as size;
"

# Count objects
docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -d cmdb_insight -c "
  SELECT object_type_name, COUNT(*) 
  FROM objects 
  GROUP BY object_type_name;
"

Full Stack (Alternative)

Als je de hele stack in Docker wilt draaien:

docker-compose up -d

Dit start:

• PostgreSQL
• Backend (in Docker)
• Frontend (in Docker)

Backend Development

Met alleen PostgreSQL draaiend:

# In backend directory
cd backend
npm install
npm run dev

Backend draait op http://localhost:3001

Frontend Development

# In frontend directory
cd frontend
npm install
npm run dev

Frontend draait op http://localhost:5173

Environment Variables

Maak een .env bestand in de root:

# Database (voor backend)
DATABASE_TYPE=postgres
DATABASE_URL=postgresql://cmdb:cmdb-dev@localhost:5432/cmdb_insight

# Jira (optioneel)
JIRA_HOST=https://jira.zuyderland.nl
JIRA_PAT=your_token

# AI (optioneel)
ANTHROPIC_API_KEY=your_key

Database Access

Quick Access

Using the script:

# Connect using psql
./scripts/open-database.sh psql

# Or via Docker
./scripts/open-database.sh docker

# Or get connection string for GUI tools
./scripts/open-database.sh url

Direct psql command:

psql postgresql://cmdb:cmdb-dev@localhost:5432/cmdb_insight

Via Docker:

docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -d cmdb_insight

GUI Tools

pgAdmin (Free, Web-based):

• Download: https://www.pgadmin.org/download/
• Connection: postgresql://cmdb:cmdb-dev@localhost:5432/cmdb_insight

DBeaver (Free, Cross-platform):

• Download: https://dbeaver.io/download/
• Create new PostgreSQL connection with connection string above

TablePlus (macOS, Paid but has free tier):

• Download: https://tableplus.com/
• Create new PostgreSQL connection

Useful SQL Commands

-- List all tables
\dt

-- Describe a table structure
\d objects
\d attribute_values
\d classification_history

-- View object counts
SELECT object_type_name, COUNT(*) 
FROM objects 
GROUP BY object_type_name;

-- View classification history
SELECT * FROM classification_history 
ORDER BY timestamp DESC 
LIMIT 10;

-- Check database size
SELECT pg_size_pretty(pg_database_size('cmdb_insight')) as size;

---

Troubleshooting

Port Already in Use

Als poort 5432 al in gebruik is:

# In docker-compose.dev.yml, wijzig:
ports:
  - "5433:5432"  # Gebruik 5433 lokaal

En update je .env:

DATABASE_PORT=5433

Connection Refused

# Check of container draait
docker ps | grep postgres

# Check logs
docker-compose -f docker-compose.dev.yml logs postgres

# Test connection
docker-compose -f docker-compose.dev.yml exec postgres pg_isready -U cmdb

Database Not Found

De database wordt automatisch aangemaakt bij eerste start van de backend. Of maak handmatig:

docker-compose -f docker-compose.dev.yml exec postgres psql -U cmdb -c "CREATE DATABASE cmdb_insight;"