bookmarksite/docs/TROUBLESHOOTING_SETUP.md

# Setup Troubleshooting Guide

## Step-by-Step Manual Setup

Let's go through each step manually to identify where the issue occurs.

### Step 1: Check Prerequisites

```bash
# Check Node.js version (should be 16+)
node --version

# Check npm version
npm --version

# Check if PostgreSQL is installed and running
psql --version

# Check if PostgreSQL service is running
# On Ubuntu/Debian:
sudo systemctl status postgresql

# On macOS:
brew services list | grep postgresql

# On Windows:
# Check Services in Task Manager for PostgreSQL
```

### Step 2: Database Setup (Most Common Issue)

```bash
# Start PostgreSQL if not running
# Ubuntu/Debian:
sudo systemctl start postgresql

# macOS:
brew services start postgresql

# Connect to PostgreSQL (try different approaches)
# Option 1: Default postgres user
sudo -u postgres psql

# Option 2: Your system user
psql -U postgres

# Option 3: Specify host
psql -h localhost -U postgres

# Once connected, create databases:
CREATE DATABASE bookmark_manager;
CREATE DATABASE bookmark_manager_test;

# Create a user (optional but recommended)
CREATE USER bookmark_user WITH PASSWORD 'secure_password_123';
GRANT ALL PRIVILEGES ON DATABASE bookmark_manager TO bookmark_user;
GRANT ALL PRIVILEGES ON DATABASE bookmark_manager_test TO bookmark_user;

# List databases to verify
\l

# Exit PostgreSQL
\q
```

### Step 3: Backend Setup

```bash
# Navigate to backend directory
cd backend

# Install dependencies (this might take a while)
npm install

# If npm install fails, try:
npm install --legacy-peer-deps

# Or clear cache first:
npm cache clean --force
npm install
```

### Step 4: Environment Configuration

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

# Edit the .env file with your actual values
nano .env
# OR
code .env
# OR
vim .env
```

**Edit your `.env` file with these values:**

```env
# Server Configuration
NODE_ENV=development
PORT=3001

# Database Configuration (CHANGE THESE)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=bookmark_manager
DB_USER=postgres
DB_PASSWORD=your_actual_postgres_password
DB_SSL=false

# JWT Configuration (CHANGE THIS)
JWT_SECRET=your_very_long_random_secret_key_at_least_32_characters_long
JWT_EXPIRES_IN=24h

# Email Configuration (OPTIONAL - can skip for now)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
EMAIL_FROM=your_email@gmail.com

# Application Configuration
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
BASE_URL=http://localhost:3001

# Security Configuration
BCRYPT_SALT_ROUNDS=12
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
AUTH_RATE_LIMIT_MAX=5
```

### Step 5: Test Database Connection

```bash
# Test if you can connect to the database with your credentials
psql -h localhost -U postgres -d bookmark_manager

# If this works, exit with:
\q
```

### Step 6: Initialize Database Tables

```bash
# Try to initialize the database
npm run db:init

# If this fails, let's check what's available:
npm run

# Try individual database commands:
npm run db:status
npm run db:diagnostics
```

### Step 7: Start the Application

```bash
# Try starting in development mode
npm run dev

# If that fails, try:
npm start

# If both fail, try running the server directly:
node server.js
```

## Common Error Solutions

### Error: "Database not connected"

**Solution:**
1. Make sure PostgreSQL is running
2. Check your database credentials in `.env`
3. Test connection manually:
   ```bash
   psql -h localhost -U postgres -d bookmark_manager
   ```

### Error: "ECONNREFUSED" or "Connection refused"

**Solution:**
1. PostgreSQL is not running:
   ```bash
   # Ubuntu/Debian:
   sudo systemctl start postgresql
   
   # macOS:
   brew services start postgresql
   ```

2. Wrong host/port in `.env`:
   ```env
   DB_HOST=localhost
   DB_PORT=5432
   ```

### Error: "database does not exist"

**Solution:**
```bash
# Connect to PostgreSQL and create the database
sudo -u postgres psql
CREATE DATABASE bookmark_manager;
CREATE DATABASE bookmark_manager_test;
\q
```

### Error: "authentication failed"

**Solution:**
1. Check your PostgreSQL password
2. Try connecting as postgres user:
   ```bash
   sudo -u postgres psql
   ```
3. Reset postgres password if needed:
   ```bash
   sudo -u postgres psql
   ALTER USER postgres PASSWORD 'newpassword';
   ```

### Error: "npm install" fails

**Solution:**
```bash
# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

# If still fails, try:
npm install --legacy-peer-deps
```

### Error: "Port 3001 already in use"

**Solution:**
```bash
# Find what's using the port
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or change the port in .env:
PORT=3002
```

## Minimal Test Setup

If you're still having issues, let's try a minimal setup:

```bash
# 1. Just test if Node.js works
cd backend
node -e "console.log('Node.js works!')"

# 2. Test if we can connect to PostgreSQL
psql -U postgres -c "SELECT version();"

# 3. Test if npm install worked
npm list --depth=0

# 4. Test if we can start the server without database
# Comment out database initialization in server.js temporarily
```

## Get Help

**Please share the specific error messages you're seeing, including:**

1. What command you ran
2. The exact error message
3. Your operating system
4. Node.js version (`node --version`)
5. PostgreSQL version (`psql --version`)

**Common commands to get system info:**
```bash
# System info
uname -a

# Node.js version
node --version

# npm version
npm --version

# PostgreSQL version and status
psql --version
sudo systemctl status postgresql  # Linux
brew services list | grep postgresql  # macOS
```

This will help me provide more specific solutions for your setup issues.